The following plugin provides functionality available through Pipeline-compatible steps. Read more about how to integrate steps into your Pipeline in the Steps section of the Pipeline Syntax page.

For a list of other such plugins, see the Pipeline Steps Reference page.

Azure Container Service Plugin

acsDeploy: Deploy to Azure Container Service (AKS)

  • azureCredentialsId : String
    The Azure Service Principal credentials used to communicate with the Azure services. Check the following documentation for more information about the service principal:
  • resourceGroupName : String
    Resource group of the target Azure Container Service.
  • containerService : String
    The name of the Azure Container Service. Refer to the following documentation on how to setup Azure Container Service:
  • sshCredentialsId : String

    The username and private key credential used to authenticate with the ACS clusters master node. This is the private key paired with the SSH RSA public key provided when you create the ACS cluster (see Deploy a Docker container hosting solution using the Azure portal ).

    The username and key credentials can be updated from Azure Portal. Find the Virtual Machine for your ACS cluster master node from the portal, and you can update the credential from SUPPORT + TROUBLESHOOTING >>> Reset password page.

  • configFilePaths : String

    The path patterns for the specific cluster (Kubernetes, DC/OS, Docker Swarm) configurations you want to deploy, in the form of Ant glob syntax.

  • containerRegistryCredentials (optional)
    All the credentials needed for pulling images from private repositories. Specify multiple entries if your deployments need to pull images from multiple, private repositories that require authentication.
      Array / List of Nested Object
    • url : String
      URL to the Docker registry you are using. May be left blank to use the public DockerHub registry (currently https://index.docker.io/v1/).
    • credentialsId : String
  • dcosDockerCredenditalsPathShared : boolean (optional)

    Determine if the Docker credentials archive upload path specified above is shared among all the agents.

    To ease the shared files access, we may create share file storage for all the DC/OS agent nodes as this documentation (Create and mount a file share to a DC/OS cluster) suggests. With the help of the shared storage, we only need to upload the Docker credentials archive to the shared storage once, and all the agent nodes get the access to the resource immediately.

    Check this option if the Docker credentials archive upload path is a shared storage path.

  • dcosDockerCredentialsPath : String (optional)

    The path on the DC/OS cluster agent nodes to store the docker credentials archive docker.tar.gz. Only absolute path is allowed here. Environment variable substitution is enabled for the path input. Due to the limitation in the underlying Mesos fetcher used by Marathon, special characters that need URI escaping and the character set {single quote ('), back slash (\), nul (\0)}, are not allowed in the path, otherwise it will fail to load the resource before running the container.

    If not specified, the plugin will generate a path specific for the build with the following pattern.

    
    /home/<linuxAdminUser>/acs-plugin-dcos.docker/<unique-name-generated-for-the-build>

    The plugin will generate the docker credentials archive with the credentials provided, and upload the archive to the given path for all the agents. You can use it to construct the URI used in your Marathon application definition.

    
    "uris":  [
        "file://<filled-path>/docker.tar.gz"
    ]

    The URI will be exposed with the environment variable $MARATHON_DOCKER_CFG_ARCHIVE_URI. You can use this in your Marathon application definition when the "Enable Variable Substitution in Config" option is enabled. This helps when the upload path is not filled and generated by the build, or if the path changes frequently.

    Note that if an archive exists in the target path already, the build will overwrite that file.

    Reference: Marathon: Using a Private Docker Registry

  • enableConfigSubstitution : boolean (optional)
    Substitute variables (in the form $VARIABLE or ${VARIABLE}) in the configuration with values from Jenkins environment variables.

    This allows you to use dynamic values produced during the build in your Kubernetes or DC/OS configurations, e.g., a dynamically generated Docker image tag which will be used later in the deployment.

  • secretName : String (optional)
    The secret name that you can use in the Kubernetes Deployment configuration for the imagePullSecrets entry. Environment variable substitution are supported for the name input, so you can use available environment variables to construct the name dynamically, e.g., some-secret-$BUILD_NUMBER. The name should be in the pattern [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*, i.e., dot (.) concatenated sequences of hyphen (-) separated alphanumeric words. (See Kubernetes Names)

    If left blank, the plugin will generate a name based on the build name.

    The secret name will be exposed with the environment variable $KUBERNETES_SECRET_NAME. You can use this in your Kubernetes configuration to reference the updated secret when the "Enable Variable Substitution in Config" option is enabled.

    
    apiVersion: extensions/v1beta1
    kind: Deployment
    metadata:
      name: nginx
    spec:
      replicas: 1
      template:
        metadata:
          labels:
            app: nginx
        spec:
          containers:
          - name: nginx
            image: some.private.registry.domain/nginx
            ports:
            - containerPort: 80
          imagePullSecrets:
          - name: $KUBERNETES_SECRET_NAME
    

    Note that once the secret is created, it will only be updated by the plugin. You have to manually delete it when it is not used anymore. If this is a problem, you may use fixed name so every time the job runs, the secret gets updated and no new secret is created.

  • secretNamespace : String (optional)
    The Kubernetes namespace in which the secrets will be created with the credentials configured below.
  • swarmRemoveContainersFirst : boolean (optional)
    Stop and remove containers first.

step([$class: 'ACSDeploymentBuilder']): Deploy to Azure Container Service (AKS)

  • context
      Nested Object
    • azureCredentialsId : String
      The Azure Service Principal credentials used to communicate with the Azure services. Check the following documentation for more information about the service principal:
    • resourceGroupName : String
      Resource group of the target Azure Container Service.
    • containerService : String
      The name of the Azure Container Service. Refer to the following documentation on how to setup Azure Container Service:
    • sshCredentialsId : String

      The username and private key credential used to authenticate with the ACS clusters master node. This is the private key paired with the SSH RSA public key provided when you create the ACS cluster (see Deploy a Docker container hosting solution using the Azure portal ).

      The username and key credentials can be updated from Azure Portal. Find the Virtual Machine for your ACS cluster master node from the portal, and you can update the credential from SUPPORT + TROUBLESHOOTING >>> Reset password page.

    • configFilePaths : String

      The path patterns for the specific cluster (Kubernetes, DC/OS, Docker Swarm) configurations you want to deploy, in the form of Ant glob syntax.

    • containerRegistryCredentials (optional)
      All the credentials needed for pulling images from private repositories. Specify multiple entries if your deployments need to pull images from multiple, private repositories that require authentication.
        Array / List of Nested Object
      • url : String
        URL to the Docker registry you are using. May be left blank to use the public DockerHub registry (currently https://index.docker.io/v1/).
      • credentialsId : String
    • dcosDockerCredenditalsPathShared : boolean (optional)

      Determine if the Docker credentials archive upload path specified above is shared among all the agents.

      To ease the shared files access, we may create share file storage for all the DC/OS agent nodes as this documentation (Create and mount a file share to a DC/OS cluster) suggests. With the help of the shared storage, we only need to upload the Docker credentials archive to the shared storage once, and all the agent nodes get the access to the resource immediately.

      Check this option if the Docker credentials archive upload path is a shared storage path.

    • dcosDockerCredentialsPath : String (optional)

      The path on the DC/OS cluster agent nodes to store the docker credentials archive docker.tar.gz. Only absolute path is allowed here. Environment variable substitution is enabled for the path input. Due to the limitation in the underlying Mesos fetcher used by Marathon, special characters that need URI escaping and the character set {single quote ('), back slash (\), nul (\0)}, are not allowed in the path, otherwise it will fail to load the resource before running the container.

      If not specified, the plugin will generate a path specific for the build with the following pattern.

      
      /home/<linuxAdminUser>/acs-plugin-dcos.docker/<unique-name-generated-for-the-build>

      The plugin will generate the docker credentials archive with the credentials provided, and upload the archive to the given path for all the agents. You can use it to construct the URI used in your Marathon application definition.

      
      "uris":  [
          "file://<filled-path>/docker.tar.gz"
      ]

      The URI will be exposed with the environment variable $MARATHON_DOCKER_CFG_ARCHIVE_URI. You can use this in your Marathon application definition when the "Enable Variable Substitution in Config" option is enabled. This helps when the upload path is not filled and generated by the build, or if the path changes frequently.

      Note that if an archive exists in the target path already, the build will overwrite that file.

      Reference: Marathon: Using a Private Docker Registry

    • enableConfigSubstitution : boolean (optional)
      Substitute variables (in the form $VARIABLE or ${VARIABLE}) in the configuration with values from Jenkins environment variables.

      This allows you to use dynamic values produced during the build in your Kubernetes or DC/OS configurations, e.g., a dynamically generated Docker image tag which will be used later in the deployment.

    • secretName : String (optional)
      The secret name that you can use in the Kubernetes Deployment configuration for the imagePullSecrets entry. Environment variable substitution are supported for the name input, so you can use available environment variables to construct the name dynamically, e.g., some-secret-$BUILD_NUMBER. The name should be in the pattern [a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*, i.e., dot (.) concatenated sequences of hyphen (-) separated alphanumeric words. (See Kubernetes Names)

      If left blank, the plugin will generate a name based on the build name.

      The secret name will be exposed with the environment variable $KUBERNETES_SECRET_NAME. You can use this in your Kubernetes configuration to reference the updated secret when the "Enable Variable Substitution in Config" option is enabled.

      
      apiVersion: extensions/v1beta1
      kind: Deployment
      metadata:
        name: nginx
      spec:
        replicas: 1
        template:
          metadata:
            labels:
              app: nginx
          spec:
            containers:
            - name: nginx
              image: some.private.registry.domain/nginx
              ports:
              - containerPort: 80
            imagePullSecrets:
            - name: $KUBERNETES_SECRET_NAME
      

      Note that once the secret is created, it will only be updated by the plugin. You have to manually delete it when it is not used anymore. If this is a problem, you may use fixed name so every time the job runs, the secret gets updated and no new secret is created.

    • secretNamespace : String (optional)
      The Kubernetes namespace in which the secrets will be created with the credentials configured below.
    • swarmRemoveContainersFirst : boolean (optional)
      Stop and remove containers first.

Was this page helpful?

Please submit your feedback about this page through this quick form.

Alternatively, if you don't wish to complete the quick form, you can simply indicate if you found this page helpful?

    


See existing feedback here.