Kubectl task

Article
06/24/2021
6 minutes to read

Azure Pipelines

Use this task to deploy, configure, or update a Kubernetes cluster by running kubectl commands.

Service Connection

The task works with two service connection types: Azure Resource Manager and Kubernetes Service Connection, described below.

Azure Resource Manager

Parameters	Description
`connectionType` Service connection type	(Required) Azure Resource Manager when using Azure Kubernetes Service, or Kubernetes Service Connection for any other cluster. Default value: Azure Resource Manager
`azureSubscriptionEndpoint` Azure subscription	(Required) Name of the Azure Service Connection.
`azureResourceGroup` Resource group	(Required) Name of the resource group within the subscription.
`kubernetesCluster` Kubernetes cluster	(Required) Name of the AKS cluster.
`useClusterAdmin` Use cluster admin credentials	(Optional) Use cluster administrator credentials instead of default cluster user credentials. This will ignore role based access control.
`namespace` Namespace	(Optional) The namespace on which the kubectl commands are to be run. If unspecified, the default namespace is used.

This YAML example shows how Azure Resource Manager is used to refer to the Kubernetes cluster. This is to be used with one of the kubectl commands and the appropriate values required by the command.

variables:
  azureSubscriptionEndpoint: Contoso
  azureContainerRegistry: contoso.azurecr.io
  azureResourceGroup: Contoso
  kubernetesCluster: Contoso
  useClusterAdmin: false

steps:
- task: Kubernetes@1
  displayName: kubectl apply
  inputs:
    connectionType: Azure Resource Manager
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)
    useClusterAdmin: $(useClusterAdmin)

Kubernetes Service Connection

Parameters	Description
`kubernetesServiceEndpoint` Kubernetes service connection	(Required) Select a Kubernetes service connection.
`namespace` Namespace	(Optional) The namespace on which the kubectl commands are to be run. If not specified, the default namespace is used.

This YAML example shows how a Kubernetes Service Connection is used to refer to the Kubernetes cluster. This is to be used with one of the kubectl commands and the appropriate values required by the command.

- task: Kubernetes@1
  displayName: kubectl apply
  inputs:
    connectionType: Kubernetes Service Connection
    kubernetesServiceEndpoint: Contoso

Commands

The command input accepts one of the following kubectl commands:

apply, create, delete, exec, expose, get, login, logout, logs, run, set, or top.

Parameters	Description
`command` Command	(Required) Applies a configuration to a resource by filename or stdin. Default value: apply
`useConfigurationFile` Use configuration files	(Optional) Use Kubernetes configuration files with the kubectl command. Enter the filename, directory, or URL of the Kubernetes configuration files. Default value: false
`arguments` Arguments	(Optional) Arguments for the specified kubectl command.

This YAML example demonstrates the apply command:

- task: Kubernetes@1
  displayName: kubectl apply using arguments
  inputs:
    connectionType: Azure Resource Manager
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)
    command: apply
    arguments: -f mhc-aks.yaml

This YAML example demonstrates the use of a configuration file with the apply command:

- task: Kubernetes@1
  displayName: kubectl apply using configFile
  inputs:
    connectionType: Azure Resource Manager
    azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
    azureResourceGroup: $(azureResourceGroup)
    kubernetesCluster: $(kubernetesCluster)
    command: apply
    useConfigurationFile: true
    configuration: mhc-aks.yaml

Secrets

Kubernetes objects of type secret are intended to hold sensitive information such as passwords, OAuth tokens, and ssh keys. Putting this information in a secret is safer and more flexible than putting it verbatim in a pod definition or in a Docker image. Azure Pipelines simplifies the addition of ImagePullSecrets to a service account, or setting up of any generic secret, as described below.

ImagePullSecret

Parameters	Description
`secretType` Type of secret	(Required) Create or update an ImagePullSecret or any other generic secret. Acceptable values: dockerRegistry for ImagePullSecret or generic for any other type of secret. Default value: dockerRegistry
`containerRegistryType` Container registry type	(Required) Acceptable values: Azure Container Registry, or Container Registry for any other registry. Default value: Azure Container Registry
`azureSubscription EndpointForSecrets` Azure subscription	(Required if secretType == dockerRegistry and containerRegistryType == Azure Container Registry) Azure Resource Manager service connection scoped to the subscription containing the Azure Container Registry for which the ImagePullSecret is to be set up.
`azureContainerRegistry` Azure container registry	(Required if secretType == dockerRegistry and containerRegistryType == Azure Container Registry) The Azure Container Registry for which the ImagePullSecret is to be set up.
`secretName` Secret name	(Optional) Name of the secret.
`forceUpdate` Force update secret	(Optional) Delete the secret if it exists and create a new one with updated values. Default value: true

This YAML example demonstrates the setting up of ImagePullSecrets:

    - task: Kubernetes@1
      displayName: kubectl apply for secretType dockerRegistry
      inputs:
        azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
        azureResourceGroup: $(azureResourceGroup)
        kubernetesCluster: $(kubernetesCluster)
        command: apply
        arguments: -f mhc-aks.yaml
        secretType: dockerRegistry
        containerRegistryType: Azure Container Registry
        azureSubscriptionEndpointForSecrets: $(azureSubscriptionEndpoint)
        azureContainerRegistry: $(azureContainerRegistry)
        secretName: mysecretkey2
        forceUpdate: true

Generic Secrets

Parameters	Description
`secretType` Type of secret	(Required) Create or update an ImagePullSecret or any other generic secret. Acceptable values: dockerRegistry for ImagePullSecret or generic for any other type of secret. Default value: dockerRegistry
`secretArguments` Arguments	(Optional) Specify keys and literal values to insert in the secret. For example, `--from-literal=key1=value1 --from-literal=key2="top secret"`
`secretName` Secret name	(Optional) Name of the secret.

This YAML example creates generic secrets from literal values specified for the secretArguments input:

    - task: Kubernetes@1
      displayName: secretType generic with literal values
      inputs:
        azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
        azureResourceGroup: $(azureResourceGroup)
        kubernetesCluster: $(kubernetesCluster)
        command: apply
        arguments: -f mhc-aks.yaml
        secretType: generic
        secretArguments: --from-literal=contoso=5678
        secretName: mysecretkey

Pipeline variables can be used to pass arguments for specifying literal values, as shown here:

    - task: Kubernetes@1
      displayName: secretType generic with pipeline variables
      inputs:
        azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
        azureResourceGroup: $(azureResourceGroup)
        kubernetesCluster: $(kubernetesCluster)
        command: apply
        arguments: -f mhc-aks.yaml
        secretType: generic
        secretArguments: --from-literal=contoso=$(contosovalue)
        secretName: mysecretkey

ConfigMap

ConfigMaps allow you to decouple configuration artifacts from image content to maintain portability for containerized applications.

Parameters	Description
`configMapName` ConfigMapName	(Optional) Name of the ConfigMap.
`forceUpdateConfigMap` Force update configmap	(Optional) Delete the configmap if it exists and create a new one with updated values. Default value: false
`useConfigMapFile` Use file	(Optional) Create a ConfigMap from an individual file, or from multiple files by specifying a directory. Default value: false
`configMapFile` ConfigMap File	(Required if useConfigMapFile == true) Specify a file or directory that contains the configMaps. Note that this will use the `--from-file` argument.
`configMapArguments` Arguments	(Optional) Specify keys and literal values to insert in configMap. For example, `--from-literal=key1=value1 --from-literal=key2="top secret"`

This YAML example creates a ConfigMap by pointing to a ConfigMap file:

    - task: Kubernetes@1
      displayName: kubectl apply
      inputs:
        configMapName: myconfig
        useConfigMapFile: true
        configMapFile: src/configmap

This YAML example creates a ConfigMap by specifying the literal values directly as the configMapArguments input, and setting forceUpdate to true:

    - task: Kubernetes@1
      displayName: configMap with literal values
      inputs:
        azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
        azureResourceGroup: $(azureResourceGroup)
        kubernetesCluster: $(kubernetesCluster)
        command: apply
        arguments: -f mhc-aks.yaml
        secretType: generic
        secretArguments: --from-literal=contoso=$(contosovalue)
        secretName: mysecretkey4
        configMapName: myconfig
        forceUpdateConfigMap: true
        configMapArguments: --from-literal=myname=contoso

You can use pipeline variables to pass literal values when creating ConfigMap, as shown here:

    - task: Kubernetes@1
      displayName: configMap with pipeline variables
      inputs:
        azureSubscriptionEndpoint: $(azureSubscriptionEndpoint)
        azureResourceGroup: $(azureResourceGroup)
        kubernetesCluster: $(kubernetesCluster)
        command: apply
        arguments: -f mhc-aks.yaml
        secretType: generic
        secretArguments: --from-literal=contoso=$(contosovalue)
        secretName: mysecretkey4
        configMapName: myconfig
        forceUpdateConfigMap: true
        configMapArguments: --from-literal=myname=$(contosovalue)

Advanced

Parameters	Description
`versionOrLocation` Version	(Optional) Explicitly choose a version of kubectl to be used, or specify the path (location) of the kubectl binary. Default value: version
`versionSpec` Version spec	(Required if versionOrLocation == version) The version of the kubectl to be used. Examples: 1.7.0, 1.x.0, 4.x.0, 6.10.0, >=6.10.0 Default value: 1.7.0
`checkLatest` Check for latest version	(Optional) If true, a check for the latest version of kubectl is performed. Default value: false
`specifyLocation` Specify location	(Required) Full path to the kubectl.exe file.
`cwd` Working directory	(Optional) Working directory for the Kubectl command. Default value: $(System.DefaultWorkingDirectory)
`outputFormat` Output format	(Optional) Acceptable values: json or YAML. Default value: json. You can leave it blank explicitly like `outputFormat: ''` to default to the kubectl's outputFormat

Troubleshooting

My Kubernetes cluster is behind a firewall and I am using hosted agents. How can I deploy to this cluster?

You can grant hosted agents access through your firewall by allowing the IP addresses for the hosted agents. For more details, see Agent IP ranges

Open source

This task is open source on GitHub. Feedback and contributions are welcome.