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

  • Artigo

Você pode criar instâncias de extensão em um cluster do 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 examine a lista de extensões disponíveis no momento.

Pré-requisitos

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

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

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

    Se as extensões connectedk8s e k8s-extension já estiverem instalados, verifique se eles estão atualizados para a versão mais recente usando os seguintes comandos:

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

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

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 dos Insights de Contêiner do Azure Monitor em um cluster do Kubernetes habilitado para o 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"
}

Observação

O serviço não pode reter informações confidenciais por mais de 48 horas. Se os agentes do Kubernetes habilitados para Azure Arc não tiverem conectividade de rede por mais de 48 horas e não puderem determinar se devem criar uma extensão no cluster, a extensão fará a transição para o estado Failed. Depois que isso acontecer, você precisará executar k8s-extension create novamente para criar um novo recurso do Azure de extensão.

Os Insights de Contêiner do Azure Monitor é uma extensão singleton (apenas uma necessária por cluster). Você precisará limpar as instalações anteriores do gráfico Helm dos Insights de Contêiner do Azure Monitor (sem extensões) antes de instalar o mesmo 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 Descrição
--name Nome da instância da extensão
--extension-type O tipo de extensão que você deseja instalar no cluster. Por exemplo: Microsoft.AzureMonitor.Containers, microsoft.azuredefender.kubernetes
--scope Escopo da instalação para a extensão: cluster ou namespace
--cluster-name Nome do recurso do Kubernetes habilitado para Azure Arc no qual a instância de extensão precisa 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 precisa ser criada. Para a maioria dos cenários, use connectedClusters, que corresponde aos clusters do 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.

Observação

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 para true ou, em vez disso, pode definir a versão da instância de extensão manualmente usando o parâmetro --version. Recomendamos habilitar atualizações automáticas para versões secundárias e de patch para que você sempre tenha os patches de segurança e os recursos mais recentes.

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

Nome do parâmetro Descrição
--auto-upgrade-minor-version Propriedade booliana que determina se a versão secundária da extensão é atualizada automaticamente. A configuração padrão é true. Se esse parâmetro for definido como true, você não poderá definir o parâmetro 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 da 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 a fim de controlar sua funcionalidade. Eles são passados como pares key=value separados por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, --configuration-settings-file não poderá ser usado no mesmo comando.
--configuration-settings-file Caminho para um arquivo JSON com pares key=value a serem usados para passar as configurações para a extensão. Se esse parâmetro for usado no comando, --configuration-settings não poderá ser usado no mesmo comando.
--configuration-protected-settings Configurações que não são recuperáveis usando GET chamadas à API ou comandos az k8s-extension show. Normalmente usado para passar configurações confidenciais. Eles são passados como pares key=value separados por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, --configuration-protected-settings-file não poderá ser usado no mesmo comando.
--configuration-protected-settings-file Caminho para um arquivo JSON com pares key=value a serem usados para passar configurações confidenciais para a extensão. Se esse parâmetro for usado no comando, --configuration-protected-settings não poderá ser usado no mesmo comando.
--release-namespace Esse parâmetro indica o namespace no qual a versão será criada. Relevante somente se scope estiver definido como cluster.
--release-train Os autores de extensão podem publicar versões em conjuntos de versões diferentes, como Stable, Preview etc. Se esse parâmetro não for definido explicitamente, Stable será usado como padrão.
--target-namespace Indica o namespace no 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. Relevante somente se scope estiver definido como namespace.

Mostrar detalhes da extensão

Para exibir detalhes de uma instância de extensão instalada atualmente, 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"
  }
]

Atualizar instância de extensão

Observação

Confira a documentação do tipo de extensão específico para entender as configurações específicas em --configuration-settings e --configuration-protected-settings que podem ser atualizadas. Para --configuration-protected-settings, todas as configurações devem ser fornecidas, mesmo que apenas uma configuração esteja sendo atualizada. Se qualquer uma dessas configurações for omitida, ela será considerada obsoleta e será excluída.

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 auto-upgrade-minor-version de uma instância de extensão do 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 Descrição
--name Nome da instância da 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 precisa ser criada. Para clusters do Kubernetes habilitados para Azure Arc, use connectedClusters. Para clusters do AKS, use managedClusters.

Parâmetros opcionais para atualização

Nome do parâmetro Descrição
--auto-upgrade-minor-version Propriedade booliana que especifica se a versão secundária da extensão é atualizada automaticamente. A configuração padrão é true. Se esse parâmetro for definido como true, você não poderá definir o parâmetro 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 da extensão). Não deverá ser fornecida se a versão secundária da atualização automática estiver definida como true.
--configuration-settings Configurações que podem ser passadas para a extensão a fim de controlar sua funcionalidade. Eles são passados como pares key=value separados por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, --configuration-settings-file não poderá ser usado no mesmo comando. Somente 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 pares key=value a serem usados para passar as configurações de configuração para a extensão. Se esse parâmetro for usado no comando, --configuration-settings não poderá ser usado no mesmo comando.
--configuration-protected-settings Configurações que não são recuperáveis usando GET chamadas à API ou comandos az k8s-extension show. Normalmente usado para passar configurações confidenciais. Eles são passados como pares key=value separados por espaço após o nome do parâmetro. Se esse parâmetro for usado no comando, --configuration-protected-settings-file não poderá ser usado no mesmo comando. Quando você atualiza uma configuração protegida, todas as configurações protegidas devem ser especificadas. Se qualquer uma dessas configurações for omitida, ela será considerada obsoleta e será excluída.
--configuration-protected-settings-file Caminho para um arquivo JSON com pares key=value a serem usados para passar configurações confidenciais para a extensão. Se esse parâmetro for usado no comando, --configuration-protected-settings não poderá ser usado no mesmo comando.
--scope Escopo da instalação da extensão – cluster ou namespace.
--release-train Os autores de extensão podem publicar versões em conjuntos de versões diferentes, como Stable, Preview etc. Se esse parâmetro não for definido explicitamente, Stable será usado como padrão.

Atualizar instância de extensão

Conforme 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 atualizações automáticas. Se você definir auto-upgrade-minor-version como false, precisará 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 significativas inesperadas com atualizações de versão principais.

Para atualizar manualmente uma instância de extensão, use k8s-extension update e defina o parâmetro version 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

Observação

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

Próximas etapas