> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# circleci/azure-aks

An orb for working with Azure AKS.
Project homepage: https://github.com/CircleCI-Public/azure-aks-orb


## Commands

### create-cluster

Creates an AKS cluster and optionally the required resource group.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `admin-username` | string |  | Specify the name of the user account to create on node VMs for SSH access.
 |
| `client-secret` | env_var_name | AZURE_SP_PASSWORD | Name of environment variable that stores the secret associated with the service principal. Required if "service-principal" is specified.
 |
| `cluster-name` | string |  | Name of the AKS cluster to be created
 |
| `create-resource-group` | boolean | false | Whether the specified resource group is to be created.
 |
| `dns-name-prefix` | string |  | Prefix for hostnames that are created.
If not specified, a hostname will be generated based on the managed cluster and resource group names.
 |
| `generate-ssh-keys` | boolean | false | Generate SSH public and private key files if missing. The keys will be stored in the ~/.ssh directory.
 |
| `kubernetes-version` | string |  | Version of Kubernetes to use for creating the cluster, such as "1.11.8" or "1.12.6".
 |
| `location` | string |  | Location that the AKS cluster will be created in.
The location is required if "create-resource-group" is set to true.
 |
| `no-output-timeout` | string | 45m | Elapsed time that the cluster creation command can run on CircleCI without output.
The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `no-ssh-key` | boolean | true | Do not use or create a local SSH key.
 |
| `no-wait` | boolean | false | Enable this to skip waiting for the long-running operation to finish.
 |
| `node-count` | integer | -1 | Configures the number of nodes in the Kubernetes node pool.
A value of -1 will be ignored.
 |
| `node-osdisk-size` | integer | -1 | Size in GB of the OS disk for each node in the node pool. Minimum 30 GB.
A value of -1 will be ignored.
 |
| `node-vm-size` | string |  | Size of Virtual Machines to create as Kubernetes nodes.
 |
| `resource-group` | string |  | Resource group that the AKS cluster will be created in.
 |
| `resource-group-tags` | string |  | Space-separated tags in 'key[=value]' format, for the resource group to be created.
Only effective when create-resource-group is set to true.
 |
| `service-principal` | env_var_name | AZURE_SP | Name of environment variable that stores the service principal used for authentication to Azure APIs.
 |
| `show-az-command` | boolean | false | Whether to show the az command(s) run.
 |
| `skip-kubectl-install` | boolean | false | Whether to skip the installation of kubectl.
 |
| `ssh-key-value` | string |  | Public key path or key contents to install on node VMs for SSH access.
 |
| `subscription` | string |  | Name or ID of subscription.
 |
| `tags` | string |  | Space-separated tags in 'key[=value]' format, for the cluster.
 |

### delete-cluster

Deletes the cluster and optionally the associated resources.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster-name` | string |  | Name of the cluster to be deleted.
 |
| `delete-resource-group` | boolean | false | Whether the specified resource group is to be deleted.
 |
| `delete-service-principal` | boolean |  | Whether the service principal for the cluster should also be deleted.
 |
| `no-output-timeout` | string | 30m | Elapsed time that the cluster deletion command can run without output.
The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `no-wait` | boolean | false | Enable this to skip waiting for the long-running operation to finish.
 |
| `resource-group` | string |  | Resource group that the cluster is in.
 |
| `show-az-command` | boolean | false | Whether to show the az command(s) used.
 |
| `subscription` | string |  | Name or ID of subscription.
 |

### update-kubeconfig-with-credentials

Allows the kubectl client to work with an AKS cluster.
Updates the kubectl configuration file with AKS cluster access credentials.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster-name` | string |  | The name of the cluster for which to create a kubeconfig entry.
 |
| `file` | string |  | Kubernetes configuration file to update. Use "-" to print YAML to stdout instead.
 |
| `get-admin-credentials` | boolean | false | Get cluster administrator credentials instead of cluster user credentials.
 |
| `install-kubectl` | boolean | false | Whether to install kubectl
 |
| `overwrite-existing` | boolean | false | Whether to overwrite any existing cluster entry with the same name.
 |
| `perform-login` | boolean | false | Whether to perform a login with the Azure CLI.
(See https://circleci.com/orbs/registry/orb/circleci/azure-cli#commands-login-with-user-or-service-principal
for the required environment variables)
 |
| `resource-group` | string |  | Resource group that the AKS cluster belongs to.
 |
| `subscription` | string |  | Name or ID of subscription.
 |

## Jobs

### create-cluster

Creates an AKS cluster and optionally the required resource group.

Requirements: Login to Azure is done via the azure-cli Orb and
requires environment variables storing the Azure user
or Service Principal credentials to be defined (See:
https://circleci.com/orbs/registry/orb/circleci/azure-cli#commands-login-with-user-or-service-principal)


| Parameter | Type | Default | Description |
|---|---|---|---|
| `admin-username` | string |  | Specify the name of the user account to create on node VMs for SSH access.
 |
| `client-secret` | env_var_name | AZURE_SP_PASSWORD | Name of environment variable that stores the secret associated with the service principal. Required if "service-principal" is specified.
 |
| `cluster-name` | string |  | Name of the AKS cluster to be created
 |
| `create-resource-group` | boolean | false | Whether the specified resource group is to be created.
 |
| `dns-name-prefix` | string |  | Prefix for hostnames that are created.
If not specified, a hostname will be generated based on the managed cluster and resource group names.
 |
| `executor` | executor | default | Executor to use for this job.
 |
| `generate-ssh-keys` | boolean | false | Generate SSH public and private key files if missing. The keys will be stored in the ~/.ssh directory.
 |
| `kubernetes-version` | string |  | Version of Kubernetes to use for creating the cluster, such as "1.11.8" or "1.12.6".
 |
| `location` | string |  | Location that the AKS cluster will be created in.
The location is required if "create-resource-group" is set to true.
 |
| `no-output-timeout` | string | 45m | Elapsed time that the cluster creation command can run on CircleCI without output.
The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `no-ssh-key` | boolean | true | Do not use or create a local SSH key.
 |
| `no-wait` | boolean | false | Enable this to skip waiting for the long-running operation to finish.
 |
| `node-count` | integer | -1 | Configures the number of nodes in the Kubernetes node pool.
A value of -1 will be ignored.
 |
| `node-osdisk-size` | integer | -1 | Size in GB of the OS disk for each node in the node pool. Minimum 30 GB.
A value of -1 will be ignored.
 |
| `node-vm-size` | string |  | Size of Virtual Machines to create as Kubernetes nodes.
 |
| `resource-group` | string |  | Resource group that the AKS cluster will be created in.
 |
| `resource-group-tags` | string |  | Space-separated tags in 'key[=value]' format, for the resource group to be created.
Only effective when create-resource-group is set to true.
 |
| `service-principal` | env_var_name | AZURE_SP | Name of environment variable that stores the service principal used for authentication to Azure APIs.
 |
| `show-az-command` | boolean | false | Whether to show the az command(s) run.
 |
| `skip-kubectl-install` | boolean | false | Whether to skip the installation of kubectl.
 |
| `ssh-key-value` | string |  | Public key path or key contents to install on node VMs for SSH access.
 |
| `subscription` | string |  | Name or ID of subscription.
 |
| `tags` | string |  | Space-separated tags in 'key[=value]' format, for the cluster to be created.
 |

### delete-cluster

Deletes the AKS cluster and optionally the associated resources.

Requirements: Login to Azure is done via the azure-cli Orb and
requires environment variables storing the Azure user
or Service Principal credentials to be defined (See:
https://circleci.com/orbs/registry/orb/circleci/azure-cli#commands-login-with-user-or-service-principal)


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster-name` | string |  | Name of the AKS cluster to be deleted.
 |
| `delete-resource-group` | boolean | false | Whether the specified resource group is to be deleted.
 |
| `delete-service-principal` | boolean |  | Whether the service principal for the cluster should also be deleted.
 |
| `executor` | executor | default | Executor to use for this job.
 |
| `get-admin-credentials` | boolean | false | Get cluster administrator credentials instead of cluster user credentials.
 |
| `no-output-timeout` | string | 30m | Elapsed time that the cluster deletion command can run without output.
The string is a decimal with unit suffix, such as “20m”, “1.25h”, “5s”
 |
| `no-wait` | boolean | false | Enable this to skip waiting for the long-running operation to finish.
 |
| `resource-group` | string |  | Resource group that the AKS cluster is in.
 |
| `show-az-command` | boolean | false | Whether to show the az command(s) used.
 |
| `subscription` | string |  | Name or ID of subscription.
 |

### delete-helm-release

Deletes a helm release.

Requirements: helm should be installed on the cluster.
Login to Azure is done via the azure-cli Orb and
requires environment variables storing the Azure user
or Service Principal credentials to be defined (See:
https://circleci.com/orbs/registry/orb/circleci/azure-cli#commands-login-with-user-or-service-principal)


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster-name` | string |  | The name of the AKS cluster.
 |
| `executor` | executor | default | Executor to use for this job.
 |
| `get-admin-credentials` | boolean | false | Get cluster administrator credentials instead of cluster user credentials.
 |
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `purge` | boolean | false | Whether to remove the release from the store and make its name free for
later use
 |
| `release-name` | string |  | Specify the release to be deleted.
 |
| `resource-group` | string |  | Resource group that the AKS cluster is in.
 |
| `subscription` | string |  | Name or ID of subscription.
 |
| `tiller-namespace` | string |  | Specify the namespace of Tiller
 |
| `timeout` | integer | -1 | Specify time in seconds to wait for any individual Kubernetes operation
(like Jobs for hooks)
A value of -1 will be ignored.
 |
| `tls` | boolean | false | Enable TLS for the request
 |
| `tls-ca-cert` | string |  | Path to TLS CA certificate file
 |
| `tls-cert` | string |  | Path to TLS certificate file
 |
| `tls-hostname` | string |  | The server name used to verify the hostname on the returned
certificates from the server
 |
| `tls-key` | string |  | Path to TLS key file
 |
| `tls-verify` | boolean | false | Enable TLS for request and verify remote
 |

### install-helm-chart

Installs a helm chart into the AKS cluster.

Requirements: Login to Azure is done via the azure-cli Orb and
requires environment variables storing the Azure user
or Service Principal credentials to be defined (See:
https://circleci.com/orbs/registry/orb/circleci/azure-cli#commands-login-with-user-or-service-principal)


| Parameter | Type | Default | Description |
|---|---|---|---|
| `chart` | string |  | Specify for installation a chart reference (e.g. stable/mariadb),
or a path to a packaged chart (e.g. ./nginx-1.2.3.tgz),
or a path to an unpacked chart directory (e.g. ./nginx)
or an absolute URL (e.g. https://example.com/charts/nginx-1.2.3.tgz)
 |
| `cluster-name` | string |  | The name of the AKS cluster.
 |
| `executor` | executor | default | Executor to use for this job.
 |
| `get-admin-credentials` | boolean | false | Get cluster administrator credentials instead of cluster user credentials.
 |
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `release-name` | string |  | Specify a name for the release.
 |
| `resource-group` | string |  | Resource group that the AKS cluster is in.
 |
| `subscription` | string |  | Name or ID of subscription.
 |
| `tiller-namespace` | string |  | Specify the namespace of Tiller
 |
| `tls` | boolean | false | Enable TLS for the request
 |
| `tls-ca-cert` | string |  | Path to TLS CA certificate file
 |
| `tls-cert` | string |  | Path to TLS certificate file
 |
| `tls-hostname` | string |  | The server name used to verify the hostname on the returned
certificates from the server
 |
| `tls-key` | string |  | Path to TLS key file
 |
| `tls-verify` | boolean | false | Enable TLS for request and verify remote
 |
| `values-to-override` | string |  | Override values in a chart using the --set flag of the helm install
command. Format: key1=val1,key2=val2
 |
| `wait` | boolean | true | Whether to wait for the installation to be complete
 |

### install-helm-on-cluster

Installs helm onto the AKS cluster.
Note: Parameters like tiller-tls need to be set to
apply security configurations to the tiller configuration.

Requirements: Login to Azure is done via the azure-cli Orb and
requires environment variables storing the Azure user
or Service Principal credentials to be defined (See:
https://circleci.com/orbs/registry/orb/circleci/azure-cli#commands-login-with-user-or-service-principal)


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster-name` | string |  | The name of the AKS cluster.
 |
| `enable-cluster-wide-admin-access` | boolean | false | Allow tiller to have admin access to the entire AKS cluster
by creating a role binding with a cluster-admin role
and a service account with name as specified by the service-account
parameter or defaulting to "tiller".
Note: This is a convenience option but is typically not advisable
in a production cluster for security reasons.
 |
| `executor` | executor | default | Executor to use for this job.
 |
| `get-admin-credentials` | boolean | false | Get cluster administrator credentials for updating kubeconfig
instead of cluster user credentials.
 |
| `resource-group` | string |  | Resource group that the AKS cluster is in.
 |
| `service-account` | string |  | Name of service account to Tiller to use.
Note: A role binding which specifies a role
and a service account with the specified name, must
be created in advance, unless
enable-cluster-wide-admin-access is set to true.
 |
| `subscription` | string |  | Name or ID of subscription.
 |
| `tiller-ca-cert` | string |  | The path to CA root certificate
 |
| `tiller-namespace` | string |  | Specify the namespace of Tiller
 |
| `tiller-tls` | boolean | false | Install Tiller with TLS enabled
 |
| `tiller-tls-cert` | string |  | The path to TLS certificate file to install with Tiller
 |
| `tiller-tls-hostname` | string |  | The server name used to verify the hostname on the returned
certificates from Tiller
 |
| `tiller-tls-key` | string |  | The path to TLS key file to install with Tiller
 |
| `tiller-tls-verify` | boolean | false | Install Tiller with TLS enabled and to verify remote certificates
 |
| `wait` | boolean | true | Block until Tiller is running and ready to receive requests
 |

### update-container-image

Updates the container image(s) of a resource on AKS.

Requirements: Login to Azure is done via the azure-cli Orb and
requires environment variables storing the Azure user
or Service Principal credentials to be defined (See:
https://circleci.com/orbs/registry/orb/circleci/azure-cli#commands-login-with-user-or-service-principal)


| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster-name` | string |  | The name of the cluster where the resource is to be managed.
 |
| `container-image-updates` | string |  | Specify a list of container image updates
(space-delimited name value pairs in the form
CONTAINER_NAME_1=CONTAINER_IMAGE_1 ... CONTAINER_NAME_N=CONTAINER_IMAGE_N)
to be applied to the resource via `kubectl set image`.
e.g. "busybox=busybox nginx=nginx:1.9.1"
 |
| `executor` | executor | default | Executor to use for this job.
 |
| `get-admin-credentials` | boolean | false | Get cluster administrator credentials instead of cluster user credentials.
 |
| `get-rollout-status` | boolean | false | Get the status of the rollout.
This can only be used for resource types that are valid
for usage with `kubectl rollout` subcommands.
 |
| `namespace` | string |  | The kubernetes namespace that should be used.
 |
| `pinned-revision-to-watch` | string |  | Pin a specific revision to be watched and abort watching if it is rolled
over by another revision.
Only effective if get-rollout-status is set to true.
 |
| `record` | boolean | false | Whether to record the update
 |
| `resource-file-path` | string |  | Path to file used to update the resource.
Either resource-file-path or resource-name need to be specified.
 |
| `resource-group` | string |  | Resource group that the AKS cluster is in.
 |
| `resource-name` | string |  | Resource name in the format TYPE/NAME e.g. deployment/nginx-deployment
Either resource-file-path or resource-name need to be specified.
This is required if get-rollout-status is set to true.
 |
| `show-kubectl-command` | boolean | false | Whether to show the kubectl command used.
 |
| `subscription` | string |  | Name or ID of subscription.
 |
| `watch-rollout-status` | boolean | true | Whether to watch the status of the latest rollout until it's done.
Only effective if get-rollout-status is set to true.
 |
| `watch-timeout` | string |  | The length of time to wait before ending the watch, zero means never.
Any other values should contain a corresponding time unit (e.g. 1s, 2m, 3h).
Only effective if get-rollout-status is set to true.
 |

## Executors

### azure-docker

Microsoft's Azure CLI Docker image


### default

Debian-based circleci/python Docker image to use


| Parameter | Type | Default | Description |
|---|---|---|---|
| `debian-release` | string | stretch |  |
| `python-version` | string | 3.7 |  |

## Examples

### create-aks-cluster

Create an AKS cluster, test it, and tear it down.


```yaml
jobs:
  test-cluster:
    executor: azure-aks/default
    parameters:
      cluster-name:
        description: |
          Name of the AKS cluster
        type: string
      resource-group:
        description: |
          Resource group that the cluster is in
        type: string
    steps:
      - azure-aks/update-kubeconfig-with-credentials:
          cluster-name: << parameters.cluster-name >>
          install-kubectl: true
          perform-login: true
          resource-group: << parameters.resource-group >>
      - run:
          command: |
            kubectl get services
          name: Test cluster
orbs:
  azure-aks: circleci/azure-aks@0.2.1
  kubernetes: circleci/kubernetes@0.4.0
version: 2.1
workflows:
  deployment:
    jobs:
      - azure-aks/create-cluster:
          cluster-name: my-aks-demo
          create-resource-group: true
          generate-ssh-keys: true
          location: eastus
          resource-group: my-aks-demo-rg
      - test-cluster:
          cluster-name: my-aks-demo
          requires:
            - azure-aks/create-cluster
          resource-group: my-aks-demo-rg
      - azure-aks/delete-cluster:
          cluster-name: my-aks-demo
          delete-resource-group: true
          delete-service-principal: true
          requires:
            - test-cluster
          resource-group: my-aks-demo-rg
```

### create-k8s-deployment

Create a kubernetes deployment.


```yaml
jobs:
  create-deployment:
    executor: azure-aks/default
    parameters:
      cluster-name:
        description: |
          Name of the AKS cluster
        type: string
      resource-group:
        description: |
          Resource group that the cluster is in
        type: string
    steps:
      - checkout
      - azure-aks/update-kubeconfig-with-credentials:
          cluster-name: << parameters.cluster-name >>
          install-kubectl: true
          perform-login: true
          resource-group: << parameters.resource-group >>
      - kubernetes/create-or-update-resource:
          resource-file-path: tests/nginx-deployment/deployment.yaml
          resource-name: deployment/nginx-deployment
orbs:
  azure-aks: circleci/azure-aks@0.2.1
  kubernetes: circleci/kubernetes@0.4.0
version: 2.1
workflows:
  deployment:
    jobs:
      - azure-aks/create-cluster:
          cluster-name: aks-demo-deployment
          create-resource-group: true
          generate-ssh-keys: true
          location: eastus
          resource-group: aks-demo-deployment-rg
      - create-deployment:
          cluster-name: aks-demo-deployment
          requires:
            - azure-aks/create-cluster
          resource-group: aks-demo-deployment-rg
      - azure-aks/update-container-image:
          cluster-name: aks-demo-deployment
          container-image-updates: nginx=nginx:1.9.1
          post-steps:
            - kubernetes/delete-resource:
                resource-names: nginx-deployment
                resource-types: deployment
                wait: true
          record: true
          requires:
            - create-deployment
          resource-group: aks-demo-deployment-rg
          resource-name: deployment/nginx-deployment
      - azure-aks/delete-cluster:
          cluster-name: aks-demo-deployment
          delete-resource-group: true
          delete-service-principal: true
          requires:
            - azure-aks/update-container-image
          resource-group: aks-demo-deployment-rg
```

### install-helm-chart

Install a helm chart on a cluster.


```yaml
orbs:
  azure-aks: circleci/azure-aks@0.2.1
  kubernetes: circleci/kubernetes@0.4.0
version: 2.1
workflows:
  deployment:
    jobs:
      - azure-aks/create-cluster:
          cluster-name: my-aks-helm-demo
          create-resource-group: true
          generate-ssh-keys: true
          location: eastus
          resource-group: my-aks-helm-demo-rg
      - azure-aks/install-helm-on-cluster:
          cluster-name: my-aks-helm-demo
          enable-cluster-wide-admin-access: true
          requires:
            - azure-aks/create-cluster
          resource-group: my-aks-helm-demo-rg
      - azure-aks/install-helm-chart:
          chart: stable/grafana
          cluster-name: my-aks-helm-demo
          release-name: grafana-release
          requires:
            - azure-aks/install-helm-on-cluster
          resource-group: my-aks-helm-demo-rg
      - azure-aks/delete-helm-release:
          cluster-name: my-aks-helm-demo
          release-name: grafana-release
          requires:
            - azure-aks/install-helm-chart
          resource-group: my-aks-helm-demo-rg
      - azure-aks/delete-cluster:
          cluster-name: my-aks-helm-demo
          delete-resource-group: true
          delete-service-principal: true
          requires:
            - azure-aks/delete-helm-release
          resource-group: my-aks-helm-demo-rg
```