Configurando o Acesso ao Cluster

Saiba mais sobre as etapas para configurar o acesso aos clusters que você cria usando o Container Engine for Kubernetes (OKE). Depois de concluir as etapas, você pode começar a usar o kubectl para gerenciar o cluster.

Para acessar um cluster usando o kubectl, defina um arquivo de configuração do Kubernetes (normalmente conhecido como arquivo "kubeconfig") para o cluster. O arquivo kubeconfig (por padrão, chamado config e armazenado no diretório $HOME/.kube) fornece os detalhes necessários para acessar o cluster. Depois de configurar o arquivo kubeconfig, você pode começar a usar o kubectl para gerenciar o cluster.

As etapas a serem seguidas ao configurar o arquivo kubeconfig dependem de como você deseja acessar o cluster:

Para acessar o cluster usando o kubectl no Cloud Shell, execute um comando da CLI do Oracle Cloud Infrastructure na janela do Cloud Shell para configurar o arquivo kubeconfig.

Consulte Configurando o Acesso do Cloud Shell a Clusters.
Para acessar o cluster usando uma instalação local do kubectl:
- Gere um par de chaves de assinatura de API (se você ainda não tiver um).
- Faça upload da chave pública do par de chaves de assinatura de API.
- Instale e configure a CLI do Oracle Cloud Infrastructure.
- Configure o arquivo kubeconfig.
Consulte Configurando o Acesso Local a Clusters.

Configurando o Acesso do Cloud Shell a Clusters

Quando o ponto final da API do Kubernetes de um cluster tem um endereço IP público, você pode acessar o cluster no Cloud Shell configurando um arquivo kubeconfig.

Observação

Para acessar um cluster com um ponto final da API privada do Kubernetes no Cloud Shell, você pode configurar um bastion usando o serviço Oracle Cloud Infrastructure Bastion. Para obter mais informações, consulte Configurando um Bastion para Acesso ao Cluster.

Para configurar o arquivo kubeconfig:

Etapa 1: Configurar o arquivo kubeconfig

Abra o menu de navegação e clique em Serviços ao Desenvolvedor. Em Contêineres e Artefatos, clique em Clusters do Kubernetes (OKE).
Escolha um Compartimento no qual você tem permissão para trabalhar.
Na página Lista de Clusters, clique no nome do cluster que você deseja acessar usando o kubectl. A página Cluster mostra detalhes do cluster.
Clique no botão Acessar Cluster para exibir a caixa de diálogo Acessar Seu Cluster.
Clique em Acesso do Cloud Shell.
Clique em Iniciar Cloud Shell para exibir a janela do Cloud Shell. Para obter mais informações sobre o Cloud Shell (incluindo a política necessária do IAM), consulte Cloud Shell.
Execute o comando da CLI do Oracle Cloud Infrastructure para configurar o arquivo kubeconfig e salve-o em um local acessível para o kubectl.

Por exemplo, digite o seguinte comando (ou copie-o e cole-o da caixa de diálogo Acessar Seu Cluster) na janela do Cloud Shell:
```
oci ce cluster create-kubeconfig --cluster-id ocid1.cluster.oc1.phx.aaaaaaaaae... --file $HOME/.kube/config  --region us-phoenix-1 --token-version 2.0.0 --kube-endpoint PUBLIC_ENDPOINT
```
em que:
- ocid1.cluster.oc1.phx.aaaaaaaaae... é o OCID do cluster atual. Por praticidade, o comando na caixa de diálogo Acessar Seu Cluster já inclui o OCID do cluster.
- --kube-endpoint PUBLIC_ENDPOINT especifica adicionar o endereço IP público do ponto final da API do Kubernetes do cluster ao arquivo kubeconfig. Para obter mais informações, consulte Plano de Controle de Cluster do Kubernetes e API do Kubernetes.
Observe que, se já houver um arquivo kubeconfig no local especificado, os detalhes do cluster serão adicionados como um novo contexto ao arquivo kubeconfig existente. O elemento current-context: no arquivo kubeconfig será definido para apontar para o contexto recém-adicionado.

Dica

Para as operações da área de transferência na janela do Cloud Shell, os usuários do Windows podem usar Ctrl-C ou Ctrl-Insert para copiar e Shift-Insert para colar. Para usuários do Mac OS, use Cmd-C para copiar e Cmd-V para colar.
Se você não salvar o arquivo kubeconfig no local padrão ($HOME/.kube) ou com o nome padrão (config), defina o valor da variável de ambiente KUBECONFIG para apontar para o nome e o local do arquivo kubeconfig. Por exemplo, digite o seguinte comando na janela do Cloud Shell:
```
export KUBECONFIG=$HOME/.kube/config
```

Etapa 2: Verifique se o kubectl pode acessar o cluster

Verifique se o kubectl pode se conectar ao cluster informando o seguinte comando na janela do Cloud Shell:

$ kubectl get nodes

São mostradas informações sobre os nós do cluster.

Agora você pode usar o kubectl para executar operações no cluster.

Configurando o Acesso Local a Clusters

Quando o ponto final da API do Kubernetes de um cluster não tiver um endereço IP público, você poderá acessar o cluster de um terminal local se sua rede for pareada com a VCN do cluster.

Observação

Para acessar um cluster com um ponto final privado da API do Kubernetes em um terminal local, você também pode configurar um bastion usando o serviço Oracle Cloud Infrastructure Bastion. Para obter mais informações, consulte Configurando um Bastion para Acesso ao Cluster.

Para configurar o arquivo kubeconfig:

Etapa 1: Gere um par de chaves de assinatura de API

Se você já tiver um par de chaves de assinatura de API, vá direto para a próxima etapa. Caso contrário:

Use comandos OpenSSL para gerar o par de chaves no formato PEM necessário. Se você estiver usando o Windows, será necessário instalar o Git Bash for Windows e executar os comandos com essa ferramenta. Consulte Como Gerar uma Chave de Assinatura de API.
Copie o conteúdo da chave pública para a área de transferência (será necessário colar o valor na Console posteriormente).

Etapa 2: Faça upload da chave pública do par de chaves de assinatura da API

No canto superior direito da Console, abra o menu Perfil e clique em Definições do Usuário para exibir os detalhes.
Clique em Adicionar Chave Pública.
Cole o valor da chave pública na janela e clique em Adicionar.

A chave é submetida a upload e sua impressão digital é exibida (por exemplo, d1:b2:32:53:d3:5f:cf:68:2d:6f:8b:5f:77:8f:07:13).

Etapa 3: Instale e configure a CLI do Oracle Cloud Infrastructure

Instale a CLI versão 2.6.4 (ou mais recente) do Oracle Cloud Infrastructure Consulte Instalando a CLI.
Configure a CLI do Oracle Cloud Infrastructure. Consulte Configurando a CLI.

Etapa 4: Configurar o arquivo kubeconfig

Abra o menu de navegação e clique em Serviços ao Desenvolvedor. Em Contêineres e Artefatos, clique em Clusters do Kubernetes (OKE).
Escolha um Compartimento no qual você tem permissão para trabalhar.
Na página Lista de Clusters, clique no nome do cluster que você deseja acessar usando o kubectl. A página Cluster mostra detalhes do cluster.
Clique no botão Acessar Cluster para exibir a caixa de diálogo Acessar Seu Cluster.
Clique em Acesso Local.
Crie um diretório para conter o arquivo kubeconfig. Por padrão, o nome do diretório esperado é $HOME/.kube.

Por exemplo, no Linux, digite o seguinte comando (ou copie-o e cole-o da caixa de diálogo Acessar Seu Cluster) em uma janela de terminal local:
```
mkdir -p $HOME/.kube
```
Execute o comando da CLI do Oracle Cloud Infrastructure para configurar o arquivo kubeconfig e salve-o em um local acessível para o kubectl.

Por exemplo, no Linux, digite o seguinte comando (ou copie-o e cole-o da caixa de diálogo Acessar Seu Cluster) em uma janela de terminal local:
```
oci ce cluster create-kubeconfig --cluster-id ocid1.cluster.oc1.phx.aaaaaaaaae... --file $HOME/.kube/config  --region us-phoenix-1 --token-version 2.0.0 --kube-endpoint PRIVATE_ENDPOINT|PUBLIC_ENDPOINT
```
em que:
- ocid1.cluster.oc1.phx.aaaaaaaaae... é o OCID do cluster atual. Por praticidade, o comando na caixa de diálogo Acessar Seu Cluster já inclui o OCID do cluster.
- --kube-endpoint PRIVATE_ENDPOINT|PUBLIC_ENDPOINT especifica se adicionar o endereço IP privado ou o endereço IP público do ponto final da API do Kubernetes do cluster ao arquivo kubeconfig. Para obter mais informações, consulte Plano de Controle de Cluster do Kubernetes e API do Kubernetes.
Observe que, se já houver um arquivo kubeconfig no local especificado, os detalhes do cluster serão adicionados como um novo contexto ao arquivo kubeconfig existente. O elemento current-context: no arquivo kubeconfig será definido para apontar para o contexto recém-adicionado.
Se você não salvar o arquivo kubeconfig no local padrão ($HOME/.kube) ou com o nome padrão (config), defina o valor da variável de ambiente KUBECONFIG para apontar para o nome e o local do arquivo kubeconfig. Por exemplo, no Linux, digite o seguinte comando (ou copie-o e cole-o da caixa de diálogo Acessar Seu Cluster) em uma janela de terminal local:
```
export KUBECONFIG=$HOME/.kube/config
```

Etapa 5: Verificar se o kubectl pode acessar o cluster

Verifique se o kubectl está disponível informando o seguinte comando em uma janela de terminal local:
```
kubectl version
```
A resposta mostra:
- a versão do kubectl instalada e em execução localmente
- a versão do Kubernetes (a rigor, a versão do kube-apiserver) em execução nos nós de plano de controle do cluster
Observe que a versão do kubectl deve estar em uma versão secundária (anterior ou mais recente) da versão do Kubernetes em execução nos nós de plano de controle. Se o kubectl for mais de uma versão secundária mais antiga ou mais recente, instale uma versão apropriada do kubectl. Consulte a Kubernetes version and version skew support policy na documentação do Kubernetes.

Se o comando retornar um erro indicando que o kubectl não está disponível, instale-o (consulte a documentação do kubectl) e repita esta etapa.
Verifique se o kubectl pode se conectar ao cluster informando o seguinte comando em uma janela de terminal local:
```
kubectl get nodes
```
São mostradas informações sobre os nós do cluster.

Agora você pode usar o kubectl para executar operações no cluster.

Observações sobre Arquivos Kubeconfig

Observe o seguinte sobre os arquivos kubeconfig:

Um único arquivo kubeconfig pode incluir os detalhes de vários clusters, como vários contextos. O cluster no qual as operações serão executadas é especificado pelo elemento current-context: no arquivo kubeconfig.
Um arquivo kubeconfig inclui um comando da CLI do Oracle Cloud Infrastructure que gera dinamicamente um token de autenticação e o insere quando você executa um comando kubectl. A CLI do Oracle Cloud Infrastructure deve estar disponível no caminho executável do shell (por exemplo, $PATH no Linux).
Os tokens de autenticação gerados pelo comando da CLI do Oracle Cloud Infrastructure no arquivo kubeconfig são de curta duração, com escopo baseado no cluster e específicos para usuários individuais. Como resultado, não é possível compartilhar arquivos kubeconfig entre usuários para acessar clusters do Kubernetes.
O comando da CLI do Oracle Cloud Infrastructure no arquivo kubeconfig usa seu perfil da CLI atual ao gerar um token de autenticação. Se você tiver definido vários perfis em tenancies distintas no arquivo de configuração da CLI (por exemplo, em ~/.oci/config), especifique qual perfil será usado ao gerar o token de autenticação da seguinte maneira. Em ambos os casos, <profile-name> é o nome do perfil definido no arquivo de configuração da CLI:
- Adicione --profile à seção args: do arquivo kubeconfig da seguinte forma:
```
user:
  exec:
    apiVersion: client.authentication.k8s.io/v1beta1
    args:
    - ce
    - cluster
    - generate-token
    - --cluster-id
    - <cluster ocid>
    - --profile
    - <profile-name>
    command: oci
    env: []
```
- Defina a variável de ambiente OCI_CLI_PROFILE com o nome do perfil definido no arquivo de configuração da CLI antes de executar comandos kubectl. Por exemplo:
```
export OCI_CLI_PROFILE=<profile-name>
```
```
kubectl get nodes
```
Os tokens de autenticação gerados pelo comando da CLI do Oracle Cloud Infrastructure no arquivo kubeconfig são apropriados para autenticar usuários individuais que acessam o cluster usando o kubectl. No entanto, os tokens de autenticação gerados não são adequados se você quiser que outros processos e ferramentas acessem o cluster, como ferramentas de integração contínua e entrega contínua (CI/CD). Nesse caso, considere criar uma conta de serviço do Kubernetes e adicionar seu token de autenticação associado ao arquivo kubeconfig. Para obter mais informações, consulte Adicionando um Token de Autenticação de Conta de Serviço a um Arquivo Kubeconfig.
Uma política do serviço IAM pode ter sido definida para restringir o acesso do cluster a apenas usuários que foram verificados com autenticação de vários fatores (MFA). Se essa política existir, você precisará adicionar argumentos --profile e --auth ao arquivo kubeconfig para permitir que um usuário verificado por MFA acesse o cluster usando o kubectl, da seguinte forma. Em ambos os casos, <profile-name> é o nome do perfil do usuário verificado por MFA definido no arquivo de configuração da CLI do Oracle Cloud Infrastructure:
- Adicione os seguintes argumentos à seção args: do arquivo kubeconfig:
```
    - --profile
    - <profile-name>
    - --auth
    - security_token
```
  Por exemplo:
```
user:
  exec:
    apiVersion: client.authentication.k8s.io/v1beta1
    args:
    - ce
    - cluster
    - generate-token
    - --cluster-id
    - <cluster ocid>
    - --profile
    - <profile-name>
    - --auth
    - security_token
    command: oci
    env: []
```
- Defina a variável de ambiente OCI_CLI_PROFILE com o nome do perfil do usuário verificado por MFA definido no arquivo de configuração da CLI antes de executar os comandos kubectl. Por exemplo:
```
export OCI_CLI_PROFILE=<profile-name>
```
```
kubectl get nodes
```
Após a atualização do arquivo kubeconfig, o usuário usado para acessar o cluster deverá ser verificado por MFA. Se você tentar acessar o cluster usando um usuário que não foi verificado por MFA, a mensagem error: You must be logged in to the server (Unauthorized) será exibida.

Para obter informações sobre usuários verificados por MFA, consulte Gerenciando Autenticação Multifator.

Upgrade de Arquivos Kubeconfig da Versão 1.0.0 para a Versão 2.0.0

O Container Engine for Kubernetes atualmente suporta arquivos kubeconfig da versão 2.0.0, e não suporta mais arquivos kubeconfig da versão 1.0.0.

Os aprimoramentos nos arquivos kubeconfig versão 2.0.0 fornecem melhorias de segurança para o ambiente Kubernetes, incluindo tokens de curta duração com escopo baseado no cluster com atualização automática e suporte para principais da instância para acessar clusters do Kubernetes. Além disso, os tokens de autenticação são gerados sob demanda para cada cluster; portanto, os arquivos kubeconfig versão 2.0.0 não podem ser compartilhados entre os usuários para acessar os clusters do Kubernetes (ao contrário dos arquivos kubeconfig versão 1.0.0).

Observe que os arquivos kubeconfig da versão 2.0.0 não são compatíveis com as versões do kubectl anteriores à versão 1.11.9. Se você estiver executando o kubectl versão 1.10.x ou anterior, faça upgrade do kubectl para a versão 1.11.9 ou mais recente. Para obter mais informações sobre compatibilidade entre diferentes versões do kubernetes e do kubectl, consulte a documentação do Kubernetes.

Siga as instruções abaixo para determinar a versão atual dos arquivos kubeconfig e como fazer upgrade dos arquivos kubeconfig restantes da versão 1.0.0 para a versão 2.0.0.

Determinar a versão do arquivo kubeconfig

Para determinar a versão do arquivo kubeconfig de um cluster:

1. Em uma janela de terminal (a janela do Cloud Shell ou uma janela de terminal local, conforme apropriado), informe o seguinte comando para ver o formato do arquivo kubeconfig atualmente apontado pela variável de ambiente KUBECONFIG:

kubectl config view

2. Se o arquivo kubeconfig for da versão 1.0.0, você verá uma resposta no seguinte formato:

users:
- name: <username>
  user:
    token: <token-value>

Se você vir uma resposta no formato acima, terá de fazer upgrade do arquivo kubeconfig. Consulte Upgrade de Arquivos Kubeconfig da Versão 1.0.0 para a Versão 2.0.0.

3. Se o arquivo kubeconfig for da versão 2.0.0, você verá uma resposta no seguinte formato:

user:
  exec:
    apiVersion: client.authentication.k8s.io/v1beta1
    args:
    - ce
    - cluster
    - generate-token
    - --cluster-id
    - <cluster ocid>
    command: oci
    env: []

Se você vir uma resposta no formato acima, nenhuma outra ação será necessária.

Fazer upgrade de um arquivo kubeconfig da versão 1.0.0 para a versão 2.0.0

Para fazer upgrade de um arquivo kubeconfig da versão 1.0.0:

No caso de uma instalação local do kubectl, confirme se a versão da CLI 2.6.4 (ou mais recente) do Oracle Cloud Infrastructure está instalada informando:
```
oci -version
```
Se a versão da CLI do Oracle Cloud Infrastructure for anterior à versão 2.6.4, faça upgrade da CLI para uma versão posterior. Consulte Upgrade da CLI.
Siga as instruções apropriadas para configurar o arquivo kubeconfig para uso no Cloud Shell ou localmente (consulte Configurando o Acesso do Cloud Shell a Clusters ou Configurando o Acesso Local a Clusters). A execução do comando oci ce cluster create-kubeconfig mostrado na caixa de diálogo Acessar Seu Cluster faz upgrade do arquivo kubeconfig versão 1.0.0 existente. Se você alterar o nome ou o local do arquivo kubeconfig, defina a variável de ambiente KUBECONFIG de modo a apontar para o novo nome e localização do arquivo.
Confirme se o arquivo kubeconfig está agora na versão 2.0.0:
1. Em uma janela de terminal (a janela do Cloud Shell ou uma janela de terminal local, conforme apropriado), informe:
```
kubectl config view
```
2. Confirme se a resposta está no seguinte formato:
```
user:
  exec:
    apiVersion: client.authentication.k8s.io/v1beta1
    args:
    - ce
    - cluster
    - generate-token
    - --cluster-id
    - <cluster ocid>
    command: oci
    env: []
```