Kubernetes@1 - Kubectl v1 任务

通过运行 kubectl 命令在 Azure 容器服务中部署、配置和更新 Kubernetes 群集。

语法

# 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.

输入

connectionType - 服务连接类型
string. 当 command != logout 时，需要此选项。 允许的值：Azure Resource Manager、Kubernetes Service Connection、None。 默认值：Kubernetes Service Connection。

指定服务连接类型：将 Azure Kubernetes 服务 或 Kubernetes 服务连接用于任何其他群集时的 Azure 资源管理器。

• Kubernetes Service Connection - 允许提供 KubeConfig 文件、指定服务帐户或使用 Azure 订阅 选项导入 AKS 实例。 使用 Azure 订阅 选项导入 AKS 实例需要在服务连接配置时访问 Kubernetes 群集。
• Azure Resource Manager - 允许选择 AKS 实例。 在服务连接配置时不访问 Kubernetes 群集。
• None - 使用本地存储的预创建的 Kubernetes 配置。

有关详细信息，请参阅以下“备注”部分中的服务连接。

kubernetesServiceEndpoint - Kubernetes 服务连接
string. 当 connectionType = Kubernetes Service Connection && command != logout 时，需要此选项。

选择 Kubernetes 服务连接。

azureSubscriptionEndpoint - Azure 订阅
string. 当 connectionType = Azure Resource Manager && command != logout 时，需要此选项。

指定包含Azure 容器注册表的 Azure 资源管理器 订阅。

注意

若要配置新的服务连接，请从列表中指定 Azure 订阅，然后单击 Authorize。 如果未列出订阅，或者想要使用现有的服务主体，可以使用 或 Manage 按钮设置 Azure 服务连接Add。

azureResourceGroup - 资源组
string. 当 connectionType = Azure Resource Manager && command != logout 时，需要此选项。

选择 Azure 资源组。

kubernetesCluster - Kubernetes 群集
string. 当 connectionType = Azure Resource Manager && command != logout 时，需要此选项。

选择 Azure 托管群集。

useClusterAdmin - 使用群集管理员凭据
boolean. 可选。 在 时 connectionType = Azure Resource Manager && command != logout使用 。 默认值：false。

使用群集管理员凭据，而不是默认的群集用户凭据。

namespace - 命名 空间
string. 可选。 在 时 command != logout使用 。

使用 –namespace 标志设置 kubectl 命令的命名空间。 如果未提供命名空间，则命令将在默认命名空间中运行。

command - 命令
string. 允许的值：apply、、create、delete、exec、expose、getloginlogout、logs、run、、set、 。 top

选择要运行的 kubectl 命令。 允许的值列表提供了一些常见选项，以便在使用任务助手时便于选择，但你可以指定其他 kubectl 命令，例如 scale。 arguments使用 输入指定命令的其他参数kubectl。

useConfigurationFile - 使用配置
boolean. 可选。 在 时 command != login && command != logout使用 。 默认值：false。

指定要与 命令一起使用的 kubectl Kubernetes 配置。 可以提供 Kubernetes 配置文件的内联脚本、文件名、目录或 URL。

configurationType - 配置类型
string. 可选。 在 时 useConfigurationFile = true使用 。 允许的值： configuration (文件路径) ， inline (内联配置) 。 默认值：configuration。

指定命令的 Kubernetes 配置 kubectl 类型。 它可以是文件路径或内联脚本。

configuration - 文件路径
string. 当 configurationType = configuration 时，需要此选项。

指定用于命令的 kubernetes 配置文件的文件名、目录或 URL。

inline - 内联配置
string. 当 configurationType = inline 时，需要此选项。

指定命令的内联部署配置 kubectl 。

arguments - 参数
string. 可选。 在 时 command != login && command != logout使用 。

指定 kubectl 命令的参数。

secretType - 机密类型
string. 当 command != login && command != logout 时，需要此选项。 允许的值：dockerRegistry、generic。 默认值：dockerRegistry。

创建/更新泛型或 docker imagepullsecret。 选择 dockerRegistry 以创建/更新所选注册表的 imagepullsecret。 imagePullSecret 是一种将包含容器注册表密码的机密传递给 Kubelet 的方法，以便它可以代表 Pod 拉取专用映像。

secretArguments - 参数
string. 可选。 在 时 secretType = generic && command != login && command != logout使用 。

指定要在机密中插入的键和文本值。 例如， --from-literal=key1=value1或 --from-literal=key2="top secret"。

containerRegistryType - 容器注册表类型
string. 当 secretType = dockerRegistry && command != login && command != logout 时，需要此选项。 允许的值：Azure Container Registry、Container Registry。 默认值：Azure Container Registry。

选择容器注册表类型。 该任务可以使用 Azure 订阅详细信息来处理 Azure 容器注册表。 还支持其他标准容器注册表。

dockerRegistryEndpoint - Docker 注册表服务连接
string. 可选。 在 时 secretType = dockerRegistry && containerRegistryType = Container Registry && command != login && command != logout使用 。

选择 Docker 注册表服务连接。 所用命令需要使用注册表进行身份验证时必需。

azureSubscriptionEndpointForSecrets - Azure 订阅
string. 可选。 在 时 secretType = dockerRegistry && containerRegistryType = Azure Container Registry && command != login && command != logout使用 。

指定包含Azure 容器注册表的 Azure 资源管理器 订阅。

注意

若要配置新的服务连接，请从列表中选择 Azure 订阅，然后单击 Authorize。 如果未列出订阅，或者想要使用现有的服务主体，可以使用 或 Manage 按钮设置 Azure 服务连接Add。

azureContainerRegistry - Azure 容器注册表
string. 可选。 在 时 secretType = dockerRegistry && containerRegistryType = Azure Container Registry && command != login && command != logout使用 。

指定用于拉取容器映像和将应用程序部署到 Kubernetes 群集的Azure 容器注册表。 所用命令需要使用注册表进行身份验证时必需。

secretName - 机密名称
string. 可选。 在 时 command != login && command != logout使用 。

机密的名称。 可以在 Kubernetes YAML 配置文件中使用此机密名称。

forceUpdate - 强制更新机密
boolean. 可选。 在 时 command != login && command != logout使用 。 默认值：true。

删除机密（如果存在），并使用更新的值创建一个新机密。

configMapName - ConfigMap 名称
string. 可选。 在 时 command != login && command != logout使用 。

ConfigMaps 允许将配置项目与映像内容分离，使容器化应用程序保持可移植性。

forceUpdateConfigMap - 强制更新配置映射
boolean. 可选。 在 时 command != login && command != logout使用 。 默认值：false。

如果 configmap 存在，请将其删除，并创建一个具有更新值的新配置映射。

useConfigMapFile - 使用文件
boolean. 可选。 在 时 command != login && command != logout使用 。 默认值：false。

通过指定目录 ConfigMap ，从单个文件或多个文件创建 。

configMapFile - ConfigMap 文件
string. 当 useConfigMapFile = true && command != login && command != logout 时，需要此选项。

指定包含 configMaps 的文件或目录。

configMapArguments - 参数
string. 可选。 在 时 useConfigMapFile = false && command != login && command != logout使用 。

指定要在 中插入的 configMap键和文本值。 例如 --from-literal=key1=value1 或 --from-literal=key2="top secret"。

versionOrLocation - Kubectl
string. 允许的值： version、 location (指定位置) 。 默认值：version。

kubectl 是一个命令行接口，用于针对 Kubernetes 群集运行命令。

versionSpec - 版本规范
string. 可选。 在 时 versionOrLocation = version使用 。 默认值：1.13.2。

指定要获取的版本的版本规范。 示例： 1.7.0、 1.x.0、 4.x.0、 6.10.0、 >=6.10.0。

checkLatest - 检查最新版本
boolean. 可选。 在 时 versionOrLocation = version使用 。 默认值：false。

始终联机检查符合版本规范的最新可用版本 (stable.txt) 。除非有一个始终获取最新的特定方案，否则这通常为 false。 这会导致在可能不需要时产生下载成本，尤其是在托管生成池中。

specifyLocation - kubectl 的路径
string. 当 versionOrLocation = location 时，需要此选项。

指定文件的完整路径 kubectl.exe 。

workingDirectory - 工作目录
输入别名： cwd。 string. 默认值：$(System.DefaultWorkingDirectory)。

Kubectl 命令的工作目录。

outputFormat - 输出格式
string. 允许的值：json、yaml、none。 默认值：json。

输出格式。

任务控制选项

除了任务输入，所有任务都有控制选项。 有关详细信息，请参阅 控制选项和常见任务属性。

输出变量

此任务定义以下 输出变量，可在下游步骤、作业和阶段中使用。

KubectlOutput
存储命令的 kubectl 输出。

注解

版本 1.0 中的新增功能。

• 添加了新的服务连接类型输入，以便轻松选择 Azure AKS 群集。
• 将输出变量输入替换为我们在所有任务中添加的输出变量部分。

使用此任务可通过运行 kubectl 命令来部署、配置或更新 Kubernetes 群集。

服务连接

该任务适用于两种服务连接类型：Azure 资源管理器和 Kubernetes 服务连接，如下所述。

Azure 资源管理器

将 设置为 connectionTypeAzure Resource Manager ，并指定以azureSubscriptionEndpoint使用 Azure 资源管理器 服务连接。

此 YAML 示例演示如何使用 Azure 资源管理器来引用 Kubernetes 群集。 此代码与某个 kubectl 命令和该命令所需的适当值一起使用。

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 服务连接

将 设置为 connectionTypeKubernetes Service Connection ，并指定 kubernetesServiceEndpoint 以使用 Kubernetes 服务连接。

此 YAML 示例演示如何使用 Kubernetes 服务连接来引用 Kubernetes 群集。 此代码与某个 kubectl 命令和该命令所需的适当值一起使用。

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

访问 AKS 时的 Kubernetes 服务连接注意事项

可以使用以下任一选项创建 Kubernetes 服务连接。

• KubeConfig
• 服务帐户
• Azure 订阅

选择 Azure 订阅 选项时，Azure DevOps 需要在服务连接配置时访问 Kubernetes。 无法创建服务连接的原因可能有多种，例如，你 创建了专用群集 ，或者该群集 禁用了本地帐户。 在这些情况下，Azure DevOps 无法在服务连接配置时连接到群集，你将看到停滞的 “加载命名空间” 屏幕。

从 Kubernetes 1.24 开始， 默认情况下不再创建生存期较长的令牌。 Kubernetes 建议不要使用生存期较长的令牌。 因此，使用使用 Azure 订阅 选项创建的 Kubernetes 服务连接的任务无法访问进行身份验证所需的永久令牌，并且无法访问 Kubernetes 群集。 这还会导致冻结“ 加载命名空间” 对话框。

使用 Azure 资源管理器 服务连接访问 AKS

对于 AKS 客户，Azure 资源管理器 服务连接类型提供了连接到专用群集或禁用本地帐户的群集的最佳方法。 此方法不依赖于创建服务连接时的群集连接。 对 AKS 的访问延迟到管道运行时，其优点如下：

• 可以从自承载代理或规模集代理执行对 (专用) AKS 群集的访问，并视线到群集。
• 为使用 Azure 资源管理器 服务连接的每个任务创建令牌。 这可确保使用短期令牌连接到 Kubernetes，这是 Kubernetes 建议。
• 即使禁用了本地帐户，也可以访问 AKS。

服务连接常见问题解答

我收到以下错误消息：找不到任何与服务帐户关联的机密。 发生了什么？

你正在使用带有 Azure 订阅选项的 Kubernetes 服务连接。 我们将更新此方法以创建生存期较长的令牌。 这预计将在 5 月中旬推出。 但是，根据 Kubernetes 指南，建议开始使用 Azure 服务连接类型，而不是使用生存期较长的令牌。

我使用的是 AKS，不想更改任何内容，是否可以继续将任务与 Kubernetes 服务连接配合使用？

我们将更新此方法以创建生存期较长的令牌。 这预计将在 5 月中旬推出。 但是，请注意，此方法违反 Kubernetes 指南。

我使用的是 Kubernetes 任务和 Kubernetes 服务连接，而不是 AKS。 我应该担心吗？

任务将继续像以前一样工作。

是否会删除 Kubernetes 服务连接类型？

无论 Kubernetes 任务在何处运行，我们的 Kubernetes 任务都适用于任何 Kubernetes 群集。 Kubernetes 服务连接将继续存在。

我是 AKS 客户，一切正常，我应该采取行动吗？

无需更改任何内容。 如果在创建过程中使用 Kubernetes 服务连接并选择了 Azure 订阅，则应了解 有关使用长期令牌的 Kubernetes 指南。

我正在创建 Kubernetes 环境，但无法选择使用服务连接

如果在环境创建期间无法访问 AKS，可以使用空环境并将输入设置为 connectionType Azure 资源管理器服务连接。

我已使用 Azure Active Directory RBAC 配置了 AKS，但管道不起作用。 这些更新会解决此问题吗？

启用 AAD RBAC 后访问 Kubernetes 与令牌创建无关。 为了防止出现交互式提示，我们将在将来的更新中支持 kubelogin 。

命令

命令输入接受 kubectl 命令。

此 YAML 示例演示 apply 命令：

- 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

此 YAML 示例演示如何通过 apply 命令使用配置文件：

- 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

此 YAML 示例演示如何使用 scale 命令将部署中的副本数减少到 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)

机密

机密类型的 Kubernetes 对象旨在用于保存敏感信息，例如密码、OAuth 令牌和 SSH 密钥。 将此信息放入机密中，比一字不差地将其放入 pod 定义或 Docker 映像中要更安全且更灵活。 Azure Pipelines 简化了将 添加到 ImagePullSecrets 服务帐户或设置任何通用机密，如下所述。

ImagePullSecret

此 YAML 示例演示如何设置 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

常规机密

此 YAML 示例基于为 secretArguments 输入指定的文本值创建常规机密：

    - 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

可以使用管道变量传递用于指定文本值的参数，如下所示：

    - 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

使用 ConfigMap 可以将配置工件与映像内容分离，以保持容器化应用程序的可移植性。

此 YAML 示例通过指向 ConfigMap 文件来创建 ConfigMap：

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

此 YAML 示例通过将文本值直接指定为 configMapArguments 输入并将 forceUpdate 设置为 true 来创建 ConfigMap：

    - 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

可以在创建 ConfigMap 时使用管道变量传递文本值，如下所示：

    - 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)

故障排除

我的 Kubernetes 群集位于防火墙后面，而我使用的是托管代理。 我该如何部署到此群集？

通过允许托管代理的 IP 地址，你可以授予托管代理通过防火墙进行访问的权限。 有关更多详细信息，请参阅代理 IP 范围

要求

要求	说明
管道类型	YAML、经典版本、经典版本
运行平台	Agent、DeploymentGroup
需求	无
功能	此任务不满足作业中后续任务的任何要求。
命令限制	任意
可设置变量	任意
代理版本	所有支持的代理版本。
任务类别	部署