Important: This plugin is being retired and will be out of support as of February 29, 2024. Azure CLI is the currently recommended way to integrate Jenkins with Azure services. Refer to Tutorial: Deploy from GitHub to Azure Kubernetes Service using Jenkins for more details.
A Jenkins Plugin to deploy configurations to Azure Container Service (AKS).
It also supports deployment to the legacy Azure Container Service (ACS) with the following orchestrator:
It provides the following main functionality:
- Integration with ACS. Allow you to select existing ACS clusters and manages the authentication credentials.
- Unified configure interface for all the supported orchestrator.
- Variable substitution for configurations, which enables dynamic deployment in CI/CD.
- Docker login credentials management for pulling images from private repository.
-
AKS cluster, or an ACS cluster with the supported orchestrator
-
A Azure service principal that can be used to manage the ACS cluster
-
Configurations for the target ACS cluster orchestrator, this can be
- Kubernetes resource configurations of the following kinds:
- Deployment
- Replica Set
- Replication Controller - No rolling-update support. If that's required, consider using Deployment.
- Daemon Set
- Pod
- Job
- Service
- Ingress
- Secret - The plugin also provides secrets configuration.
- Marathon application configurations
- Docker compose configurations
In the context of container deployment, normally we should build a Docker image from the project artifacts, and push the image to a repository. This can be done with some existing plugins such as CloudBees Docker Build and Publish plugin.
- Kubernetes resource configurations of the following kinds:
- Within the Jenkins dashboard, Select a Job then select Configure
- Scroll to the "Add post-build action" drop down.
- Select "Deploy to Azure Container Service / Azure Kubernetes Service"
- Select the service principal from "Azure Credentials" dropdown. If no credentials are configured, create one.
- All resource group names will be loaded into the "Resource Group" dropdown. Select the one containing your ACS cluster.
- All the container service available in the selected resource group will be loaded into the "Container Service" dropdown. Select your target ACS cluster. (It's suggested that we use a standalone resource group to manage an ACS cluster, and do not add other resources or ACS clusters into the resource group.)
- Select the "Master Node SSH Credentials" if you are deploying to ACS. This should be the credentials of type "SSH Username with
private key", where username is the login name you specified when you create the ACS cluster (
azureuserby default), and private key is the one matching the public key you specified on the ACS cluster creation (by default that may be$HOME/.ssh/id_rsaon Linux and%USERPROFILE%\.ssh\id_rsaon Windows). - Enter the "Config Files" path of the configurations you want to deploy, in the form of Ant glob syntax. Use comma (,) to separate multiple patterns.
- If you want to dynamically update the configurations on each build, for example, use the
$BUILD_NUMBERas the tag name of the image being pulled, you can tick the "Enable Variable Substitution in Config" option and the variables (in the pattern$VARIABLEor${VARIABLE}) in the configurations will be substituted with the corresponding value if they exists in the environment variables. - If the configurations needs to pull images from private repository, click the "Docker Container Registry
Credentials..." button and add them one by one.
-
For Kubernetes, you can enter the secret name and the namespace where the secret will be created based on the credentials configured. The credentials you provided will be consolidated into a Secret resource in your Kubernetes cluster with the name you provided. You can use that secret in your Kubernetes configuration.
You can use variables in the secret name (e.g.,
$BUILD_NUMBER), to generate a secret specific to a build. The name will be exposed as environment variableKUBERNETES_SECRET_NAMEand you can use that in your Kubernetes resource configurations if the "Enable Variable Substitution in Config" option is turned on.apiVersion: extensions/v1beta1 kind: Deployment metadata: name: sample-k8s-deployment spec: replicas: 1 template: metadata: labels: app: sample-k8s-app spec: containers: - name: sample-k8s-app-container image: <username or registry URL>/<image_name>:<tag(maybe, $BUILD_NUMBER)> ports: - containerPort: 8080 imagePullSecrets: - name: $KUBERNETES_SECRET_NAME
-
For Marathon on DC/OS, you can specify the "DC/OS Docker Credentials Path", the credentials you provided will be archived into a file
docker.tar.gz, and uploaded to the agent nodes in the path you filled. You can use it to construct the URI in your Marathon config:file://<absolute_path_you_filled>/docker.tar.gzIf this path is left blank, a unique path will be generated under
$HOME/acs-plugin-dcos.docker.The URI will be exported to the environment variable
MARATHON_DOCKER_CFG_ARCHIVE_URIwhich you can use in your Marathon configuration.{ "id": "marathon-demo-app", "cmd": null, "cpus": 1, "mem": 512, "disk": 0, "instances": 1, "container": { "docker": { "image": "<username or registry URL>/<image_name>:<tag(maybe, $BUILD_NUMBER)>", "network": "BRIDGE", "portMappings": [ { "containerPort": 8080, "hostPort": 80, "protocol": "tcp", "name": "80", "labels": null } ] }, "type": "DOCKER" }, "acceptedResourceRoles": [ "slave_public" ], "uris": [ "$MARATHON_DOCKER_CFG_ARCHIVE_URI" ] } -
Add a credentials entry for each of the private Docker registries involved in your configuration. If it is hosted on DockerHub, you can leave the URL as empty; otherwise for other private registries, you need to specify the "Docker registry URL".
-
- You may verify the static configuration by clicking "Verify Configuration". This will give you basic result of the configuration quality. You need to run a sample build to verify it works as some of the contents has to be loaded at build time.
To use the plugin in pipeline, go to the Pipeline Syntax page when you configure the pipeline job, and choose acsDeploy: Deploy to Azure Container Service from the Sample Step dropdown. You can configure it and click Generate Pipeline Script which will give you
acsDeploy(azureCredentialsId: '<azure-credential-id>',
resourceGroupName: '<resource-group-name>',
containerService: '<acs-name> | <acs-type>',
sshCredentialsId: '<ssh-credentials-id>',
configFilePaths: '<configuration-file-paths>',
enableConfigSubstitution: true,
// Kubernetes
secretName: '<secret-name>',
secretNamespace: '<secret-namespace>',
// Docker Swarm
swarmRemoveContainersFirst: true,
// DC/OS Marathon
dcosDockerCredentialsPath: '<dcos-credentials-path>',
containerRegistryCredentials: [
[credentialsId: '<credentials-id>', url: '<docker-registry-url>']
])The pipeline configuration for Azure Kubernetes deployment is similar to the Kubernetes deployment in ACS.
The <acs-type> should be AKS and sshCredentialsId should be omitted.
acsDeploy(azureCredentialsId: '<azure-credential-id>',
resourceGroupName: '<resource-group-name>',
containerService: '<aks-name> | AKS',
configFilePaths: '<configuration-file-paths>',
enableConfigSubstitution: true,
secretName: '<secret-name>',
secretNamespace: '<secret-namespace>',
containerRegistryCredentials: [
[credentialsId: '<credentials-id>', url: '<docker-registry-url>']
])Azure Container Service Plugin collects usage data and sends it to Microsoft to help improve our products and services. Read our privacy statement to learn more.
You can turn off usage data collection in Manage Jenkins -> Configure System -> Azure -> Help make Azure Jenkins plugins better by sending anonymous usage statistics to Azure Application Insights.