Kubernetes@1 - Kubectl v1 task

Deploy, configure, update a Kubernetes cluster in Azure Container Service by running kubectl commands.

Syntax

# Kubectl v1
# Deploy, configure, update a Kubernetes cluster in Azure Container Service by running kubectl commands.
- task: Kubernetes@1
  inputs:
  # Kubernetes Cluster
    #connectionType: 'Kubernetes Service Connection' # 'Azure Resource Manager' | 'Kubernetes Service Connection' | 'None'. Required when command != logout. Service connection type. Default: Kubernetes Service Connection.
    #kubernetesServiceEndpoint: # string. Required when connectionType = Kubernetes Service Connection && command != logout. Kubernetes service connection. 
    #azureSubscriptionEndpoint: # string. Required when connectionType = Azure Resource Manager && command != logout. Azure subscription. 
    #azureResourceGroup: # string. Required when connectionType = Azure Resource Manager && command != logout. Resource group. 
    #kubernetesCluster: # string. Required when connectionType = Azure Resource Manager && command != logout. Kubernetes cluster. 
    #useClusterAdmin: false # boolean. Optional. Use when connectionType = Azure Resource Manager && command != logout. Use cluster admin credentials. Default: false.
    #namespace: # string. Optional. Use when command != logout. Namespace. 
  # Commands
    #command: # 'apply' | 'create' | 'delete' | 'exec' | 'expose' | 'get' | 'login' | 'logout' | 'logs' | 'run' | 'set' | 'top'. Command. 
    #useConfigurationFile: false # boolean. Optional. Use when command != login && command != logout. Use configuration. Default: false.
    #configurationType: 'configuration' # 'configuration' | 'inline'. Optional. Use when useConfigurationFile = true. Configuration type. Default: configuration.
    configuration: # string. Required when configurationType = configuration. File path. 
    #inline: # string. Required when configurationType = inline. Inline configuration. 
    #arguments: # string. Optional. Use when command != login && command != logout. Arguments. 
  # Secrets
    #secretType: 'dockerRegistry' # 'dockerRegistry' | 'generic'. Required when command != login && command != logout. Type of secret. Default: dockerRegistry.
    #secretArguments: # string. Optional. Use when secretType = generic && command != login && command != logout. Arguments. 
    #containerRegistryType: 'Azure Container Registry' # 'Azure Container Registry' | 'Container Registry'. Required when secretType = dockerRegistry && command != login && command != logout. Container registry type. Default: Azure Container Registry.
    #dockerRegistryEndpoint: # string. Optional. Use when secretType = dockerRegistry && containerRegistryType = Container Registry && command != login && command != logout. Docker registry service connection. 
    #azureSubscriptionEndpointForSecrets: # string. Optional. Use when secretType = dockerRegistry && containerRegistryType = Azure Container Registry && command != login && command != logout. Azure subscription. 
    #azureContainerRegistry: # string. Optional. Use when secretType = dockerRegistry && containerRegistryType = Azure Container Registry && command != login && command != logout. Azure container registry. 
    #secretName: # string. Optional. Use when command != login && command != logout. Secret name. 
    #forceUpdate: true # boolean. Optional. Use when command != login && command != logout. Force update secret. Default: true.
  # ConfigMaps
    #configMapName: # string. Optional. Use when command != login && command != logout. ConfigMap name. 
    #forceUpdateConfigMap: false # boolean. Optional. Use when command != login && command != logout. Force update configmap. Default: false.
    #useConfigMapFile: false # boolean. Optional. Use when command != login && command != logout. Use file. Default: false.
    #configMapFile: # string. Required when useConfigMapFile = true && command != login && command != logout. ConfigMap file. 
    #configMapArguments: # string. Optional. Use when useConfigMapFile = false && command != login && command != logout. Arguments. 
  # Advanced
    #versionOrLocation: 'version' # 'version' | 'location'. Kubectl. Default: version.
    #versionSpec: '1.13.2' # string. Optional. Use when versionOrLocation = version. Version spec. Default: 1.13.2.
    #checkLatest: false # boolean. Optional. Use when versionOrLocation = version. Check for latest version. Default: false.
    #specifyLocation: # string. Required when versionOrLocation = location. Path to kubectl. 
    #workingDirectory: '$(System.DefaultWorkingDirectory)' # string. Alias: cwd. Working directory. Default: $(System.DefaultWorkingDirectory).
    #outputFormat: 'json' # 'json' | 'yaml' | 'none'. Output format. Default: json.

Inputs

connectionType - Service connection type
string. Required when command != logout. Allowed values: Azure Resource Manager, Kubernetes Service Connection, None. Default value: Kubernetes Service Connection.

Specifies the service connection type: Azure Resource Manager when using Azure Kubernetes Service or Kubernetes Service Connection for any other cluster.

• Kubernetes Service Connection - Allows you to provide a KubeConfig file, specify a Service Account, or import an AKS instance with the Azure Subscription option. Importing an AKS instance with the Azure Subscription option requires Kubernetes cluster access at Service Connection configuration time.
• Azure Resource Manager - Lets you select an AKS instance. Does not access Kubernetes cluster at Service Connection configuration time.
• None - Use a pre-created Kubernetes configuration stored locally.

For more information, see Service connection in the following Remarks section.

kubernetesServiceEndpoint - Kubernetes service connection
string. Required when connectionType = Kubernetes Service Connection && command != logout.

Select a Kubernetes service connection.

azureSubscriptionEndpoint - Azure subscription
string. Required when connectionType = Azure Resource Manager && command != logout.

Specifies the Azure Resource Manager subscription, which contains the Azure Container Registry.

Note

To configure a new service connection, specify the Azure subscription from the list and click Authorize. If your subscription is not listed or if you want to use an existing Service Principal, you can setup an Azure service connection using the Add or Manage buttons.

azureResourceGroup - Resource group
string. Required when connectionType = Azure Resource Manager && command != logout.

Select an Azure resource group.

kubernetesCluster - Kubernetes cluster
string. Required when connectionType = Azure Resource Manager && command != logout.

Select an Azure managed cluster.

useClusterAdmin - Use cluster admin credentials
boolean. Optional. Use when connectionType = Azure Resource Manager && command != logout. Default value: false.

Use cluster administrator credentials instead of default cluster user credentials.

namespace - Namespace
string. Optional. Use when command != logout.

Set the namespace for the kubectl command by using the –namespace flag. If the namespace is not provided, the commands will run in the default namespace.

command - Command
string. Allowed values: apply, create, delete, exec, expose, get, login, logout, logs, run, set, top.

Select or specify a kubectl command to run. The list of allowed values provides some common choices for ease of selection when using the task assistant, but you can specify other kubectl commands such as scale. Use the arguments input to specify additional parameters to the specified kubectl command.

useConfigurationFile - Use configuration
boolean. Optional. Use when command != login && command != logout. Default value: false.

Specifies the Kubernetes configuration to use with the kubectl command. The inline script, filename, directory, or URL to Kubernetes configuration files can be provided.

configurationType - Configuration type
string. Optional. Use when useConfigurationFile = true. Allowed values: configuration (File path), inline (Inline configuration). Default value: configuration.

Specifies the type of Kubernetes configuration for the kubectl command. It can be a file path or an inline script.

configuration - File path
string. Required when configurationType = configuration.

Specifies the filename, directory, or URL to kubernetes configuration files that is used with the commands.

inline - Inline configuration
string. Required when configurationType = inline.

Specifies the inline deployment configuration for the kubectl command.

arguments - Arguments
string. Optional. Use when command != login && command != logout.

Arguments to the specified kubectl command.

secretType - Type of secret
string. Required when command != login && command != logout. Allowed values: dockerRegistry, generic. Default value: dockerRegistry.

Create/update a generic or docker imagepullsecret. Select dockerRegistry to create/update the imagepullsecret of the selected registry. An imagePullSecret is a way to pass a secret that contains a container registry password to the Kubelet so it can pull a private image on behalf of your Pod.

secretArguments - Arguments
string. Optional. Use when secretType = generic && command != login && command != logout.

Specifies the keys and literal values to insert in secret. For example, --from-literal=key1=value1or --from-literal=key2="top secret".

containerRegistryType - Container registry type
string. Required when secretType = dockerRegistry && command != login && command != logout. Allowed values: Azure Container Registry, Container Registry. Default value: Azure Container Registry.

Select a Container registry type. The task can use Azure Subscription details to work with an Azure Container registry. Other standard Container registries are also supported.

dockerRegistryEndpoint - Docker registry service connection
string. Optional. Use when secretType = dockerRegistry && containerRegistryType = Container Registry && command != login && command != logout.

Select a Docker registry service connection. Required for commands that need to authenticate with a registry.

azureSubscriptionEndpointForSecrets - Azure subscription
string. Optional. Use when secretType = dockerRegistry && containerRegistryType = Azure Container Registry && command != login && command != logout.

Specifies the Azure Resource Manager subscription, which contains Azure Container Registry.

Note

To configure a new service connection, select the Azure subscription from the list and click Authorize. If your subscription is not listed or if you want to use an existing Service Principal, you can setup an Azure service connection using the Add or Manage buttons.

azureContainerRegistry - Azure container registry
string. Optional. Use when secretType = dockerRegistry && containerRegistryType = Azure Container Registry && command != login && command != logout.

Specifies an Azure Container Registry which is used for pulling container images and deploying applications to the Kubernetes cluster. Required for commands that need to authenticate with a registry.

secretName - Secret name
string. Optional. Use when command != login && command != logout.

Name of the secret. You can use this secret name in the Kubernetes YAML configuration file.

forceUpdate - Force update secret
boolean. Optional. Use when command != login && command != logout. Default value: true.

Delete the secret if it exists and create a new one with updated values.

configMapName - ConfigMap name
string. Optional. Use when command != login && command != logout.

ConfigMaps allow you to decouple configuration artifacts from image content to keep containerized applications portable.

forceUpdateConfigMap - Force update configmap
boolean. Optional. Use when command != login && command != logout. Default value: false.

Delete the configmap if it exists and create a new one with updated values.

useConfigMapFile - Use file
boolean. Optional. Use when command != login && command != logout. Default value: false.

Creates a ConfigMap from an individual file or from multiple files by specifying a directory.

configMapFile - ConfigMap file
string. Required when useConfigMapFile = true && command != login && command != logout.

Specify a file or directory that contains the configMaps.

configMapArguments - Arguments
string. Optional. Use when useConfigMapFile = false && command != login && command != logout.

Specifies the keys and literal values to insert in configMap. For example, --from-literal=key1=value1 or --from-literal=key2="top secret".

versionOrLocation - Kubectl
string. Allowed values: version, location (Specify location). Default value: version.

kubectl is a command line interface for running commands against Kubernetes clusters.

versionSpec - Version spec
string. Optional. Use when versionOrLocation = version. Default value: 1.13.2.

Specifies the version spec of the version to get. Examples: 1.7.0, 1.x.0, 4.x.0, 6.10.0, >=6.10.0.

checkLatest - Check for latest version
boolean. Optional. Use when versionOrLocation = version. Default value: false.

Always checks online for the latest available version (stable.txt) that satisfies the version spec. This is typically false unless you have a specific scenario to always get latest. This will cause it to incur download costs when potentially not necessary, especially with the hosted build pool.

specifyLocation - Path to kubectl
string. Required when versionOrLocation = location.

Specifies the full path to the kubectl.exe file.

workingDirectory - Working directory
Input alias: cwd. string. Default value: $(System.DefaultWorkingDirectory).

Working directory for the Kubectl command.

outputFormat - Output format
string. Allowed values: json, yaml, none. Default value: json.

Output format.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

This task defines the following output variables, which you can consume in downstream steps, jobs, and stages.

KubectlOutput
Stores the output of the kubectl command.

Remarks

What's new in Version 1.0.

• Added a new service connection type input for easy selection of Azure AKS clusters.
• Replaced the output variable input with an output variables section that we added in all tasks.

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

Set connectionType to Azure Resource Manager and specify an azureSubscriptionEndpoint to use an Azure Resource Manager service connection.

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

Set connectionType to Kubernetes Service Connection and specify a kubernetesServiceEndpoint to use a Kubernetes service connection.

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

Kubernetes Service Connection considerations when accessing AKS

You can create a Kubernetes service connection with any of the following options.

• KubeConfig
• Service Account
• Azure Subscription

When selecting the Azure Subscription option, Kubernetes needs to be accessible to Azure DevOps at service connection configuration time. There may be various reasons a service connection cannot be created, for example you created a private cluster or the cluster has local accounts disabled. In these cases, Azure DevOps can't connect to your cluster at service connection configuration time and you'll see a stuck Loading namespaces screen.

Starting with Kubernetes 1.24, long-lived tokens are no longer created by default. Kubernetes recommends not using long-lived tokens. As a result, tasks using a Kubernetes service connection created with the Azure Subscription option don't have access to the permanent token required to authenticate and can’t access your Kubernetes cluster. This also results in the frozen Loading namespaces dialog.

Use the Azure Resource Manager Service Connection to access AKS

For AKS customers, the Azure Resource Manager service connection type provides the best method to connect to a private cluster, or a cluster that has local accounts disabled. This method is not dependent on cluster connectivity at the time you create a service connection. Access to AKS is deferred to pipeline runtime, which has the following advantages:

• Access to a (private) AKS cluster can be performed from a self-hosted or scale set agent with line of sight to the cluster.
• A token is created for every task that uses an Azure Resource Manager service connection. This ensures you are connecting to Kubernetes with a short-lived token, which is the Kubernetes recommendation.
• AKS can be accessed even when local accounts are disabled.

Service connection FAQ

I receive the following error message: Could not find any secret associated with the service account. What is happening?

You are using the Kubernetes service connection with Azure Subscription option. We are updating this method to create long-lived tokens. This is expected to be available mid-May. However, it is recommended to start using the Azure service connection type and not o use long-lived tokens as per Kubernetes guidance.

I'm using AKS and don't want to change anything, can I continue to use tasks with the Kubernetes service connection?

We are updating this method to create long-lived tokens. This is expected to be available mid-May. However, please be aware that this approach is against Kubernetes guidance.

I'm using the Kubernetes tasks and Kubernetes service connection but not AKS. Should I be concerned?

You tasks will continue to work as before.

Will the Kubernetes service connection type be removed?

Our Kubernetes tasks work with any Kubernetes cluster, regardless where they are running. The Kubernetes service connection will continue to exist.

I’m an AKS customer and everything is running fine, should I act?

There is no need to change anything. If you are using the Kubernetes service connection and selected Azure Subscription during creation, you should be aware of the Kubernetes guidance on using long-lived tokens.

I'm creating a Kubernetes Environment, and have no option to use service connections

In case you can’t access your AKS during environment creation time, you can use an empty environment and set the connectionType input to an Azure Resource Manager service connection.

I have AKS configured with Azure Active Directory RBAC, and my pipeline doesn’t work. Will these updates resolve that?

Accessing Kubernetes when AAD RBAC is enabled is unrelated to token creation. To prevent an interactive prompt, we will support kubelogin in a future update.

Commands

The command input accepts kubectl commands.

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

This YAML example shows the use of how to use the scale command to decrease the number of replicas in a deployment to 0.

- task: Kubernetes@1
      displayName: 'Scale down deployment $(k8sDeployment) to 0'
      inputs:
        connectionType: 'Kubernetes Service Connection'
        kubernetesServiceEndpoint: $(kubernetesServiceConnection)
        command: 'scale'
        arguments: 'deployment/$(k8sDeployment) --replicas=0'
        namespace: $(namespace)

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

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

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.

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)

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

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	All supported agent versions.
Task category	Deploy