Partilhar via

Implantar e gerenciar extensões de cluster do Kubernetes habilitadas para Azure Arc

  • Artigo

Você pode criar instâncias de extensão em um cluster Kubernetes habilitado para Arc, definindo parâmetros obrigatórios e opcionais, incluindo opções relacionadas a atualizações e configurações. Você também pode exibir, listar, atualizar e excluir instâncias de extensão.

Antes de começar, leia a visão geral conceitual das extensões de cluster do Kubernetes habilitadas para Arc e revise a lista de extensões atualmente disponíveis.

Pré-requisitos

  • A versão mais recente da CLI do Azure.

  • As versões mais recentes das extensões e da connectedk8s k8s-extension CLI do Azure. Instale essas extensões executando os seguintes comandos:

    az extension add --name connectedk8s
az extension add --name k8s-extension

    Se as connectedk8s extensões e k8s-extension já estiverem instaladas, certifique-se de que estão atualizadas para a versão mais recente utilizando os seguintes comandos:

    az extension update --name connectedk8s
az extension update --name k8s-extension

  • Um cluster conectado ao Kubernetes habilitado para Azure Arc existente, com pelo menos um nó do sistema operacional e do tipo linux/amd64de arquitetura. Se estiver implantando o Flux (GitOps), você poderá usar um cluster baseado em ARM64 sem um linux/amd64 nó.

Criar instância de extensão

Para criar uma nova instância de extensão, use k8s-extension create, passando valores para os parâmetros necessários.

Este exemplo cria uma instância de extensão do Azure Monitor Container Insights em um cluster Kubernetes habilitado para Azure Arc:

az k8s-extension create --name azuremonitor-containers  --extension-type Microsoft.AzureMonitor.Containers --scope cluster --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters

Saída:

{
  "autoUpgradeMinorVersion": true,
  "configurationProtectedSettings": null,
  "configurationSettings": {
    "logAnalyticsWorkspaceResourceID": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/defaultresourcegroup-eus/providers/microsoft.operationalinsights/workspaces/defaultworkspace-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-eus"
  },
  "creationTime": "2021-04-02T12:13:06.7534628+00:00",
  "errorInfo": {
    "code": null,
    "message": null
  },
  "extensionType": "microsoft.azuremonitor.containers",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/demo/providers/Microsoft.Kubernetes/connectedClusters/demo/providers/Microsoft.KubernetesConfiguration/extensions/azuremonitor-containers",
  "identity": null,
  "installState": "Pending",
  "lastModifiedTime": "2021-04-02T12:13:06.753463+00:00",
  "lastStatusTime": null,
  "name": "azuremonitor-containers",
  "releaseTrain": "Stable",
  "resourceGroup": "demo",
  "scope": {
    "cluster": {
      "releaseNamespace": "azuremonitor-containers"
    },
    "namespace": null
  },
  "statuses": [],
  "systemData": null,
  "type": "Microsoft.KubernetesConfiguration/extensions",
  "version": "2.8.2"
}

Nota

O serviço não consegue reter informações confidenciais por mais de 48 horas. Se os agentes Kubernetes habilitados para Arco do Azure não tiverem conectividade de rede por mais de 48 horas e não puderem determinar se devem ser criadas uma extensão no cluster, a extensão passará para Failed o estado. Quando isso acontecer, você precisará executar k8s-extension create novamente para criar uma nova extensão do recurso do Azure.

O Azure Monitor Container Insights é uma extensão singleton (apenas uma necessária por cluster). Você precisará limpar todas as instalações anteriores do gráfico Helm do Azure Monitor Container Insights (sem extensões) antes de instalar as mesmas por meio de extensões. Siga as instruções para excluir o gráfico Helm antes de executar az k8s-extension create.

Parâmetros obrigatórios

Os parâmetros a seguir são necessários ao usar az k8s-extension create para criar uma instância de extensão.

Nome do parâmetro Description
--name Nome da instância de extensão
--extension-type O tipo de extensão que você deseja instalar no cluster. Por exemplo: Microsoft.AzureMonitor.Containers, microsoft.azuredefender.kubernetes
--scope Âmbito da instalação para a extensão: cluster ou namespace
--cluster-name Nome do recurso Kubernetes habilitado para Azure Arc no qual a instância de extensão deve ser criada
--resource-group O grupo de recursos que contém o recurso Kubernetes habilitado para Azure Arc
--cluster-type O tipo de cluster no qual a instância de extensão deve ser criada. Para a maioria dos cenários, use connectedClusters, que corresponde aos clusters Kubernetes habilitados para Azure Arc.

Parâmetros opcionais

Use um ou mais desses parâmetros opcionais conforme necessário para seus cenários, juntamente com os parâmetros necessários.

Nota

Você pode optar por atualizar automaticamente sua instância de extensão para as versões secundárias e de patch mais recentes definindo auto-upgrade-minor-version como true, ou, em vez disso, pode definir a versão da instância de extensão manualmente usando o --version parâmetro. Recomendamos ativar as atualizações automáticas para versões secundárias e de patches, para que você sempre tenha os patches e recursos de segurança mais recentes.

Como as atualizações de versão principal podem incluir alterações de quebra, as atualizações automáticas para novas versões principais de uma instância de extensão não são suportadas. Você pode escolher quando atualizar manualmente as instâncias de extensão para uma nova versão principal.

Nome do parâmetro Description
--auto-upgrade-minor-version Propriedade booleana que determina se a versão secundária da extensão é atualizada automaticamente. A predefinição é true. Se esse parâmetro estiver definido como true, não será possível defini-lo version , pois a versão será atualizada dinamicamente. Se definido como false, a extensão não será atualizada automaticamente, mesmo para versões de patch.
--version Versão da extensão a ser instalada (versão específica para fixar a instância de extensão). Não deve ser fornecido se auto-upgrade-minor-version estiver definido como true.
--configuration-settings Configurações que podem ser passadas para a extensão para controlar sua funcionalidade. Estes são passados como pares separados key=value por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, não --configuration-settings-file poderá ser usado no mesmo comando.
--configuration-settings-file Caminho para um arquivo JSON com key=value pares a serem usados para passar definições de configuração para a extensão. Se esse parâmetro for usado no comando, não --configuration-settings poderá ser usado no mesmo comando.
--configuration-protected-settings Configurações que não podem ser recuperadas usando GET chamadas ou az k8s-extension show comandos de API. Normalmente usado para passar em configurações confidenciais. Estes são passados como pares separados key=value por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, não --configuration-protected-settings-file poderá ser usado no mesmo comando.
--configuration-protected-settings-file Caminho para um arquivo JSON com key=value pares a serem usados para passar configurações confidenciais para a extensão. Se esse parâmetro for usado no comando, não --configuration-protected-settings poderá ser usado no mesmo comando.
--release-namespace Este parâmetro indica o namespace dentro do qual a versão será criada. Apenas relevante se scope estiver definido como cluster.
--release-train Os autores de extensões podem publicar versões em diferentes trens de lançamento, como Stable, Preview, etc. Se esse parâmetro não estiver definido explicitamente, Stable será usado como padrão.
--target-namespace Indica o namespace dentro do qual a versão será criada. A permissão da conta do sistema criada para esta instância de extensão será restrita a este namespace. Apenas relevante se scope estiver definido como namespace.

Mostrar detalhes da extensão

Para exibir detalhes de uma instância de extensão atualmente instalada, use k8s-extension show, passando valores para os parâmetros obrigatórios.

az k8s-extension show --name azuremonitor-containers --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters

Saída:

{
  "autoUpgradeMinorVersion": true,
  "configurationProtectedSettings": null,
  "configurationSettings": {
    "logAnalyticsWorkspaceResourceID": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourcegroups/defaultresourcegroup-eus/providers/microsoft.operationalinsights/workspaces/defaultworkspace-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-eus"
  },
  "creationTime": "2021-04-02T12:13:06.7534628+00:00",
  "errorInfo": {
    "code": null,
    "message": null
  },
  "extensionType": "microsoft.azuremonitor.containers",
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/demo/providers/Microsoft.Kubernetes/connectedClusters/demo/providers/Microsoft.KubernetesConfiguration/extensions/azuremonitor-containers",
  "identity": null,
  "installState": "Installed",
  "lastModifiedTime": "2021-04-02T12:13:06.753463+00:00",
  "lastStatusTime": "2021-04-02T12:13:49.636+00:00",
  "name": "azuremonitor-containers",
  "releaseTrain": "Stable",
  "resourceGroup": "demo",
  "scope": {
    "cluster": {
      "releaseNamespace": "azuremonitor-containers"
    },
    "namespace": null
  },
  "statuses": [],
  "systemData": null,
  "type": "Microsoft.KubernetesConfiguration/extensions",
  "version": "2.8.2"
}

Listar todas as extensões instaladas no cluster

Para exibir uma lista de todas as extensões instaladas em um cluster, use k8s-extension list, passando valores para os parâmetros obrigatórios.

az k8s-extension list --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters

Saída:

[
  {
    "autoUpgradeMinorVersion": true,
    "creationTime": "2020-09-15T02:26:03.5519523+00:00",
    "errorInfo": {
      "code": null,
      "message": null
    },
    "extensionType": "Microsoft.AzureMonitor.Containers",
    "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/myRg/providers/Microsoft.Kubernetes/connectedClusters/myCluster/providers/Microsoft.KubernetesConfiguration/extensions/myExtInstanceName",
    "identity": null,
    "installState": "Pending",
    "lastModifiedTime": "2020-09-15T02:48:45.6469664+00:00",
    "lastStatusTime": null,
    "name": "myExtInstanceName",
    "releaseTrain": "Stable",
    "resourceGroup": "myRG",
    "scope": {
      "cluster": {
        "releaseNamespace": "myExtInstanceName1"
      }
    },
    "statuses": [],
    "type": "Microsoft.KubernetesConfiguration/extensions",
    "version": "0.1.0"
  },
  {
    "autoUpgradeMinorVersion": true,
    "creationTime": "2020-09-02T00:41:16.8005159+00:00",
    "errorInfo": {
      "code": null,
      "message": null
    },
    "extensionType": "microsoft.azuredefender.kubernetes",
    "id": "/subscriptions/0e849346-4343-582b-95a3-e40e6a648ae1/resourceGroups/myRg/providers/Microsoft.Kubernetes/connectedClusters/myCluster/providers/Microsoft.KubernetesConfiguration/extensions/defender",
    "identity": null,
    "installState": "Pending",
    "lastModifiedTime": "2020-09-02T00:41:16.8005162+00:00",
    "lastStatusTime": null,
    "name": "microsoft.azuredefender.kubernetes",
    "releaseTrain": "Stable",
    "resourceGroup": "myRg",
    "scope": {
      "cluster": {
        "releaseNamespace": "myExtInstanceName2"
      }
    },
    "type": "Microsoft.KubernetesConfiguration/extensions",
    "version": "0.1.0"
  }
]

Instância de extensão de atualização

Nota

Consulte a documentação do tipo de extensão específico para entender as configurações específicas e --configuration-settings --configuration-protected-settings que podem ser atualizadas. Para --configuration-protected-settings, espera-se que todas as configurações sejam fornecidas, mesmo que apenas uma configuração esteja sendo atualizada. Se qualquer uma dessas configurações for omitida, essas configurações serão consideradas obsoletas e excluídas.

Para atualizar uma instância de extensão existente, use k8s-extension update, passando valores para os parâmetros obrigatórios e opcionais. Os parâmetros obrigatórios e opcionais são ligeiramente diferentes daqueles usados para criar uma instância de extensão.

Este exemplo atualiza a configuração de uma instância de extensão do auto-upgrade-minor-version Azure Machine Learning para true:

az k8s-extension update --name azureml --extension-type Microsoft.AzureML.Kubernetes --scope cluster --cluster-name <clusterName> --resource-group <resourceGroupName> --auto-upgrade-minor-version true --cluster-type managedClusters

Parâmetros necessários para atualização

Nome do parâmetro Description
--name Nome da instância de extensão
--cluster-name Nome do cluster no qual a instância de extensão deve ser criada
--resource-group O grupo de recursos que contém o cluster
--cluster-type O tipo de cluster no qual a instância de extensão deve ser criada. Para clusters Kubernetes habilitados para Azure Arc, use connectedClusters. Para clusters AKS, use managedClusters.

Parâmetros opcionais para atualização

Nome do parâmetro Description
--auto-upgrade-minor-version Propriedade booleana que especifica se a versão secundária da extensão é atualizada automaticamente. A predefinição é true. Se esse parâmetro estiver definido como true, você não poderá defini-lo version , pois a versão será atualizada dinamicamente. Se definido como false, a extensão não será atualizada automaticamente, mesmo para versões de patch.
--version Versão da extensão a ser instalada (versão específica para fixar a instância de extensão). Não deve ser fornecido se auto-upgrade-minor-version estiver definido como true.
--configuration-settings Configurações que podem ser passadas para a extensão para controlar sua funcionalidade. Estes são passados como pares separados key=value por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, não --configuration-settings-file poderá ser usado no mesmo comando. Apenas as configurações que exigem uma atualização precisam ser fornecidas. As configurações fornecidas serão substituídas pelos valores especificados.
--configuration-settings-file Caminho para o arquivo JSON com key=value pares a serem usados para passar as definições de configuração para a extensão. Se esse parâmetro for usado no comando, não --configuration-settings poderá ser usado no mesmo comando.
--configuration-protected-settings Configurações que não podem ser recuperadas usando GET chamadas ou az k8s-extension show comandos de API. Normalmente usado para passar em configurações confidenciais. Estes são passados como pares separados key=value por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, não --configuration-protected-settings-file poderá ser usado no mesmo comando. Quando você atualiza uma configuração protegida, espera-se que todas as configurações protegidas sejam especificadas. Se qualquer uma dessas configurações for omitida, essas configurações serão consideradas obsoletas e excluídas.
--configuration-protected-settings-file Caminho para um arquivo JSON com key=value pares a serem usados para passar configurações confidenciais para a extensão. Se esse parâmetro for usado no comando, não --configuration-protected-settings poderá ser usado no mesmo comando.
--scope Âmbito de instalação para a extensão - cluster ou namespace.
--release-train Os autores de extensões podem publicar versões em diferentes trens de lançamento, como Stable, Preview, etc. Se esse parâmetro não estiver definido explicitamente, Stable será usado como padrão.

Instância de extensão de atualização

Como observado anteriormente, se você definir auto-upgrade-minor-version como true, a extensão será atualizada automaticamente quando uma nova versão secundária for lançada. Para a maioria dos cenários, recomendamos habilitar as atualizações automáticas. Se você definir auto-upgrade-minor-version como false, terá que atualizar a extensão manualmente se quiser uma versão mais recente.

Atualizações manuais também são necessárias para obter uma nova instância principal de uma extensão. Você pode escolher quando atualizar para evitar alterações inesperadas com as principais atualizações de versão.

Para atualizar manualmente uma instância de extensão, use k8s-extension update e defina o version parâmetro para especificar uma versão.

Este exemplo atualiza uma instância de extensão do Azure Machine Learning para a versão x.y.z:

az k8s-extension update --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters --name azureml --version x.y.z

Excluir instância de extensão

Para excluir uma instância de extensão em um cluster, use k8s-extension delete, passando valores para os parâmetros obrigatórios:

az k8s-extension delete --name azuremonitor-containers --cluster-name <clusterName> --resource-group <resourceGroupName> --cluster-type connectedClusters

Nota

O recurso do Azure que representa essa extensão é excluído imediatamente. A versão Helm no cluster associada a essa extensão só é excluída quando os agentes em execução no cluster Kubernetes têm conectividade de rede e podem entrar em contato com os serviços do Azure novamente para buscar o estado desejado.

Próximos passos