Configurar a descoberta de recursos

Configure a descoberta de recursos para gerar arquivos do Terraform para recursos existentes em seu compartimento.

Use o recurso de descoberta de recursos do OCI para:

  • Crie arquivos de estado para recursos existentes na Console e adicione esses recursos a uma configuração do Terraform.
  • Duplique sua infraestrutura existente em uma nova tenancy ou região.
  • Detecte desvio de estado para recursos atualizados.

Neste tutorial, você configura a funcionalidade de descoberta de recursos do provedor Oracle Cloud Infrastructure Terraform no seu ambiente local. Para confirmar sua configuração, execute a descoberta de recursos para extrair informações da sua tenancy e criar um script para ela.

As principais tarefas incluem:

  • Crie chaves RSA.
  • Instale arquivos binários do provedor do Terraform OCI.
  • Configure as variáveis de autenticação da API do provedor OCI Terraform.
  • Autentique os comandos da CLI do provedor do OCI.
  • Crie um script no seu ambiente, com relação aos domínios de disponibilidade na sua tenancy, por meio da funcionalidade de descoberta de recursos.
Um diagrama de um usuário conectado de um ambiente local a uma tenancy do Oracle Cloud Infrastructure. O ambiente local é o Linux e tem arquivos binários do Provedor de OCI Terraform instalados. Há uma seta do ambiente local conectado ao Registro do Terraform na nuvem. Há uma segunda seta do ambiente local que envia uma mensagem à tenancy do Oracle Cloud Infrastructure. A seta se chama 'Autenticar?'. A terceira seta vai da tenancy até o ambiente local chamado Extrair Dados. Essas setas sugerem que o usuário configurou as variáveis do provedor do OCI para serem autenticadas por sua tenancy. O usuário poderá extrair informações da tenancy usando os comandos do provedor OCI do Terraform e o Registro do Terraform. Neste exemplo, a tenancy exibe três domínios de disponibilidade e essas são as informações que a Descoberta de Recursos está extraindo para criar scripts Terraform no ambiente do usuário.

Para obter mais informações, consulte Casos de Uso e Benefícios.

Antes de Começar

Para executar este tutorial com sucesso, você precisa ter o seguinte:

MacOS ou Linux

1. Preparar

Prepare seu ambiente para autenticar e executar comandos de descoberta de recursos. Além disso, colete as informações de que sua conta precisa para autenticar seus comandos.

Criar Chaves RSA

Você cria chaves RSA para a API acessando sua conta do Oracle Cloud Infrastructure.

Observação

Se você estiver usando o Cloud Shell ou o Resource Manager, ignore a criação das chaves RSA. Você já está autenticado quando acessa a Console do OCI.
  1. Abra uma janela de terminal.
  2. Em seu diretório home, crie um diretório .oci.
    mkdir <your-home-directory>/.oci

    Exemplo para o Oracle Linux:

    mkdir /home/opc/.oci
    Observação

    Se você estiver usando o subsistema Windows para Linux (WSL), crie o diretório /.oci diretamente no ambiente Linux. Se você criar o diretório /.oci em uma pasta /mnt (sistema de arquivos do Windows), será necessário usar o comando chmod para alterar as permissões dos arquivos de configuração WSL.
  3. Gere uma chave privada de 2.048 bits em um formato PEM:
    openssl genrsa -out <your-home-directory>/.oci/<your-rsa-key-name>.pem 2048
  4. Altere as permissões para que apenas você possa ler e gravar no arquivo de chaves privadas:
    chmod 600 <your-home-directory>/.oci/<your-rsa-key-name>.pem
  5. Gere a chave pública:
    openssl rsa -pubout -in <your-home-directory>/.oci/<your-rsa-key-name>.pem -out $HOME/.oci/<your-rsa-key-name>_public.pem
  6. Copie a chave pública.
    No terminal, digite:
    cat <your-home-directory>/.oci/<your-rsa-key-name>_public.pem

    Exemplo (excerto):

    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTFqF...
    ...
    -----END PUBLIC KEY——
  7. Adicione a chave pública à sua conta de usuário.
    1. Acesse a Console do Oracle Cloud.
    2. No menu de navegação , selecione o menu Perfil Ícone do menu Perfil e, em seguida, selecione Definições do usuário ou Meu perfil, dependendo da opção que você vir.
    3. Selecione chaves de API.
    4. Selecione Adicionar chave de API.
    5. Selecione Colar uma chave pública.
    6. Cole o valor da etapa anterior, incluindo as linhas com BEGIN PUBLIC KEY e END PUBLIC KEY.
    7. Selecione Adicionar.

      A caixa de diálogo Visualização do arquivo de configuração é aberta. Por exemplo:

      [DEFAULT]
      user=ocid1.user.oc1..exampleid
      fingerprint=exampleid
      tenancy=ocid1.tenancy.oc1..exampleid
      region=us-ashburn-1
      key_file=<path to your private keyfile> # TODO
    8. Selecione Copy e cole o bloco de notas.

      A visualização do arquivo de configuração inclui informações necessárias posteriormente, como OCIDs da tenancy e do usuário, impressão digital e região.

Agora você configurou as chaves RSA para estabelecer conexão com sua conta do OCI.

Referência
Como Gerar uma Chave de Assinatura da API
Adicionar Política da Lista

Se seu nome de usuário estiver no grupo Administrators, ignore esta seção. Caso contrário, peça ao administrador para adicionar a seguinte política à sua tenancy:

allow group <a-group-that-your-username-belongs-to> to read all-resources in tenancy

Com esse privilégio, você pode listar todos os recursos da sua tenancy.

Etapas para Adicionar a Política
  1. Acesse a Console do Oracle Cloud.
  2. No menu de navegação , selecione o menu Perfil Ícone do menu Perfil e, em seguida, selecione Definições do usuário ou Meu perfil, dependendo da opção que você vir.
  3. Selecione Grupos ou Meus grupos, dependendo da opção exibida.
  4. Em um bloco de notas, copie o nome de um grupo ao qual seu nome de usuário pertence.
  5. Abra o menu de navegação e selecione Identidade e Segurança. Em Identidade, selecione Políticas.
  6. Selecione o compartimento: <your-tenancy>(root)
  7. Selecione Criar Política.
  8. Na página Criar Política, informe os seguintes valores:
    • Nome: list-resources
    • Descrição: Allow the group <a-group-that-your-username-belongs-to> to list the resources in this tenancy.
    • Compartimento: <your-tenancy>(root)
  9. Para Criador de Política, selecione Mostrar editor manual.
  10. Cole na seguinte política:
    allow group <a-group-that-your-username-belongs-to> to read all-resources in tenancy
  11. Selecione Criar.

Referência: Políticas Comuns

Reunir Informações Necessárias

Prepare as informações necessárias para autenticar seus comandos do Provedor do OCI Terraform e copie-as no seu notebook.

Observação

Se você estiver usando o Cloud Shell, só precisará localizar o <tenancy-ocid> na etapa a seguir.
  1. Colete as informações de credenciais a seguir na Console do Oracle Cloud.
    • OCID da Tenancy: <tenancy-ocid>
      • No menu de navegação, selecione o menu Perfil Ícone do menu Perfil e selecione Tenancy: <your_tenancy_name>.
    • OCID DO Usuário: <user-ocid>
      • No menu de navegação , selecione o menu Perfil Ícone do menu Perfil e, em seguida, selecione Definições do usuário ou Meu perfil, dependendo da opção que você vir.
      • Copiar OCID.
    • Impressão Digital: <fingerprint>
      • No menu de navegação , selecione o menu Perfil Ícone do menu Perfil e, em seguida, selecione Definições do usuário ou Meu perfil, dependendo da opção que você vir.
      • Selecione Chaves de API.
      • Copie a impressão digital associada à chave pública RSA feita na seção Criar Chaves RSA. O formato é: xx:xx:xx...xx.
    • Região: <region-identifier>
  2. Colete as informações a seguir do seu ambiente.
    • Caminho da Chave Privada: <rsa-private-key-path>
      • Caminho para a chave privada RSA feita em Criar Chaves RSA. Exemplo: $HOME/.oci/<your-rsa-key-name>.pem.
Instalar Provedor do OCI Terraform
Observação

Se você estiver usando o Cloud Shell, ignore esta seção.

Instale a versão mais recente dos binários do Provedor de OCI Terraform v4.2+:

  1. Em um navegador, vá para Versões HashiCorp.
  2. Selecione o link mais recente.
  3. Localize o link do seu ambiente e copie o endereço do link. Exemplo de Linux de 64 bits:
    https://releases.hashicorp.com/terraform-provider-oci/4.59.0/terraform-provider-oci_4.59.0_linux_amd64.zip
  4. Em seu ambiente, crie um diretório temporário e passe para esse diretório:
    mkdir temp
    cd temp
  5. Faça download do arquivo zip do Terraform. Por exemplo:
    wget https://releases.hashicorp.com/terraform-provider-oci/4.59.0/terraform-provider-oci_4.59.0_linux_amd64.zip
  6. Descompacte o arquivo. Por exemplo:
    unzip terraform-provider-oci_4.59.0_linux_amd64.zip
  7. Mova a pasta descompilada para /usr/local/bin. Por exemplo:
    sudo mv terraform-provider-oci_v4.59.0_x4 /usr/local/bin
    Observação

    Use sudo para o diretório /usr/local/bin se ele não permitir que você execute os comandos.
  8. Use um link simbólico para reduzir o comando terraform-provider-oci_<version>:
    sudo ln -s <source-executable> <shorter-alias>
    cd /usr/local/bin/
    sudo ln -s terraform-provider-oci_<version> tf-oci

    Para este tutorial, use tf-oci para <shorter-alias>, em vez de <source-executable>.

  9. Volte ao seu diretório home:
    cd
  10. Verifique a versão do provedor do Terraform OCI:
    Observação

    No MacOS, você precisa criar uma exceção de segurança para o arquivo executável.
    tf-oci

    Exemplo de saída: [INFO] terraform-provider-oci 4.59.0.

2. Criar um Script de Autenticação

Crie um script de shell para designar informações de autenticação às variáveis de autenticação do provedor do OCI. Sua conta do Oracle Cloud Infrastructure autentica os comandos do provedor do OCI por meio dos valores designados a esses parâmetros.

Adicionar Autenticação
Observação

Se você estiver usando o Cloud Shell ou o Resource Manager, não precisará adicionar autenticação. Prossiga para a seção 3. Descobrir um Recurso.
  1. Crie um arquivo de script executável, em algum lugar no seu PATH e atribua a ele o nome provider-oci.sh. Por exemplo, se ~/bin estiver em seu PATH, as etapas serão as seguintes:
    cd ~/bin
    touch provider-oci.sh
    chmod 755 provider-oci.sh
    ls -l

    Você obtém algo como:

    -rwxr-xr-x 1 <your-username> <your-username> 0 <date> provider-oci.sh
  2. Adicione o código a seguir a provider.tf:

    Substitua os campos com colchetes pelas informações coletadas em Reunir Informações Necessárias.

    #!/bin/bash
    export TF_VAR_tenancy_ocid="<tenancy-ocid>"
    export TF_VAR_user_ocid="<user-ocid>"
    export TF_VAR_fingerprint="<fingerprint>"
    export TF_VAR_private_key_path="<rsa-private-key-path>"
    export TF_VAR_region="<region-identifier>"
  3. Salve o arquivo provider-oci.sh.
Explicação
  • Vá para Autenticação (Descoberta de Recursos).
  • Defina as seguintes variáveis de ambiente para autenticação baseada em Chave de API:
    • TF_VAR_tenancy_ocid
    • TF_VAR_user_ocid
    • TF_VAR_fingerprint
    • TF_VAR_private_key_path
    • TF_VAR_region
Exportar Variáveis de Ambiente

Nesta seção, você executa o arquivo provider-oci.sh para adicionar as variáveis de autenticação do provedor do OCI às variáveis de ambiente.

  1. No diretório $HOME/bin, execute o arquivo provider-oci.sh.
    source provider-oci.sh
  2. Confirme se as variáveis de autenticação do provedor do OCI foram adicionadas às variáveis de ambiente.
    env | sort

    As variáveis são exibidas em ordem alfabética. Por exemplo:

    ...
    TF_VAR_fingerprint=<fingerprint>
    TF_VAR_private_key_path=<rsa-private-key-path>
    TF_VAR_region=<region-identifier>
    TF_VAR_tenancy_ocid=<tenancy-ocid>
    TF_VAR_user_ocid=<user-ocid>
    ...
  3. Para carregar as variáveis de ambiente, quando um novo shell iniciar, anexe o comando source ~/bin/provider-oci.sh a .bashrc.
    source ~/bin/provider-oci.sh

3. Descobrir um Recurso

Descubra os domínios de disponibilidade em sua tenancy.

Executar Descoberta de Recursos

Cada tenancy tem uma lista de domínios de disponibilidade. Ao descobrir os domínios de disponibilidade na sua região, você confirma que:

  • Sua conta do Oracle Cloud Infrastructure pode autenticar seus comandos do provedor do Oracle Cloud Infrastructure.
  • Você pode obter informações da sua conta com a funcionalidade de descoberta de recursos.
  1. Em seu diretório $HOME, crie um diretório chamado resource-discovery.
    cd
    mkdir resource-discovery
  2. Se você estiver usando o Cloud Shell, localize o arquivo do Provedor Terraform do OCI instalado no diretório /usr/bin.
    ls /usr/bin

    O nome do arquivo é:

    terraform-provider-oci_<version>

    Nome do arquivo de exemplo:

    terraform-provider-oci_v5.2.1
  3. Execute o seguinte comando:
    • No Cloud Shell:
      terraform-provider-oci_<version> -command=export -compartment_id=<tenancy-ocid> -services=availability_domain -output_path=$HOME/resource-discovery
    • Em sua instância de computação ou em seu ambiente local:
      tf-oci -command=export -compartment_id=<tenancy-ocid> -services=availability_domain -output_path=$HOME/resource-discovery
    Importante

    • Substitua <tenancy-ocid> pelas informações de Reunir Informações Necessárias.
    • Se você estiver usando o Cloud Shell, substitua terraform-provider-oci_<version> pelo nome do arquivo encontrado na etapa 2.

    Amostra de saída:

    ...
    INFO <date> [INFO] ===> Generating resource 'oci_identity_availability_domain.export_QnsC-US-ASHBURN-AD-1'
    INFO <date> [INFO] ===> Generating resource 'oci_identity_availability_domain.export_QnsC-US-ASHBURN-AD-2'
    INFO <date> [INFO] ===> Generating resource 'oci_identity_availability_domain.export_QnsC-US-ASHBURN-AD-3'
    ...
    INFO <date> Found 6 'availability_domain' resources. Generated under '/<home-directory>/resource-discovery/availability_domain.tf'.
    INFO <date> === COMPLETED ===
    Observação

    • O OCID da tenancy é o OCID do compartimento para o compartimento raiz. Fornecer um <compartment-ocid> específico ou seu <tenancy-ocid> tem como resultado os mesmos domínios de disponibilidade.
    • Para descobrir recursos de identidade, você não precisa mencionar um OCID de compartimento. No exemplo anterior, você obterá o mesmo resultado se removesse o compartment_id do comando. O compartment_id existe para você aprender a sintaxe de outros serviços.
Diagnóstico e Solução de Problemas
  • mensagem de erro: Falha ao consultar pacotes de provedores disponíveis:
    • Se você estiver em uma VPN, verifique suas configurações de proxy.
  • erros 401 - (Service erro:NotAuthenticated):
    • Você tem um valor incorreto para um dos seguintes itens:
      • OCID da Tenancy
      • OCID do Usuário
      • impressão digital
      • Chave privada RSA (o caminho ou a chave)
  • esse host não está disponível:
    • Você tem um valor incorreto para:
      • identificador da região
Explicação
  • Vá para Uso (Descoberta de Recursos).

    Duas opções de comando são listadas.

  • Selecione a opção de comando que usa compartment_id como um comando base:
    terraform-provider-oci -command=export -compartment_id= -output_path=
  • Atualize o comando base:
    • Em vez de terraform-provider-oci, use seu comando de link simbólico:

      tf-oci

    • Revise a seção Descrição do Parâmetro para adicionar valores apropriados aos parâmetros no comando base:
      • Use o comando export para executar a descoberta de recursos:

        -command=export

      • Adicione o OCID do compartimento no qual você está descobrindo recursos:

        -compartment_id=<tenancy-ocid>

      • Crie e depois especifique um diretório para os recursos descobertos:

        Exemplo: -output_path=$HOME/resource-discovery

  • Procure a frase availability_domain e observe as seguintes informações:
    Resources that are dependent on availability domains will be generated under availability_domain.tf file. These include:
    
        oci_core_boot_volume
        oci_file_storage_file_system
        oci_file_storage_mount_target
        oci_file_storage_snapshot
    
  • Para serviços, use:
    • availability_domain (Embora não seja um serviço, ele funciona com serviço.)
    • Exemplo: -services=availability_domain
    • Você não precisa de aspas nos nomes de serviço.
  • Construa o comando:

    Por exemplo:

    tf-oci -command=export -compartment_id=<tenancy-ocid> -services=availability_domain -output_path=$HOME/resource-discovery
    Observação

    O comando de descoberta de recursos não cria um diretório para os recursos descobertos. Crie um diretório e especifique o caminho no seu comando.
Analisar Recursos Descobertos
  1. No diretório $HOME, passe para o diretório resource-discovery.
    cd resource-discovery
  2. Exiba o conteúdo do diretório.
    ls

    Amostra de saída:

    availability_domain.tf  provider.tf  vars.tf
  3. Revise o script Terraform para ver os domínios de disponibilidade:
    cat availability_domain.tf

    Amostra de saída:

    ## This configuration was generated by terraform-provider-oci
    
    data oci_identity_availability_domain export_QnsC-US-ASHBURN-AD-1 {
      compartment_id = var.compartment_ocid
      ad_number      = "1"
    }
    data oci_identity_availability_domain export_QnsC-US-ASHBURN-AD-2 {
      compartment_id = var.compartment_ocid
      ad_number      = "2"
    }
    data oci_identity_availability_domain export_QnsC-US-ASHBURN-AD-3 {
      compartment_id = var.compartment_ocid
      ad_number      = "3"
    }
    resource oci_file_storage_file_system export_JennFS ... <some info>
    resource oci_file_storage_snapshot export_Snapshot-1 ... <some info>
    resource oci_file_storage_mount_target export_MountTarget-xxx ... <some info>
    Observação

    O script Terraform availability_domain.tf usa uma variável chamada compartment_ocid. Localize o valor dessa variável em vars.tf.
  4. Revise as variáveis:
    cat vars.tf

    Amostra de saída:

    variable compartment_ocid { default = "<tenancy-ocid>" }
    variable region { default = "us-ashburn-1" }
  5. Verifique as informações do script do provedor:
    cat provider.tf

    Amostra de saída:

    provider oci {
            region = var.region
    }
    Observação

    • O provider.tf denota que você está usando o provedor Terraform OCI com provider oci { }.
    • O arquivo provider.tf não inclui suas informações de autenticação, porque você fornece informações de autenticação por meio das variáveis de ambiente.

Parabéns! Sua conta do Oracle Cloud Infrastructure agora pode autenticar seus comandos do provedor do Terraform OCI. E seu ambiente está pronto para executar os comandos de descoberta de recursos.

Referências: