Documentação do Oracle Cloud Infrastructure

Configurar o OCI Terraform

Configure os scripts do provedor Terraform do Oracle Cloud Infrastructure, documentados no Registro do Terraform, para conexão com uma conta do OCI. Confirme a configuração extraindo informações da tenancy.

As principais tarefas incluem:

  • Crie chaves RSA.
  • Configure os scripts do provedor Terraform do Oracle Cloud Infrastructure:
    • Autentique seus scripts do Terraform.
    • Obtenha informações sobre os domínios de disponibilidade em sua tenancy.
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 o Terraform instalado. Há uma seta do Terraform no 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 seus scripts do Terraform para serem autenticados por sua tenancy. O usuário pode extrair informações da tenancy usando o 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 o usuário está extraindo.

Para obter mais informações, consulte:

Antes de Começar

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

MacOS ou Linux
Windows
Observação

Este tutorial usa um ambiente Oracle Linux VM com uma forma AMD para seus exemplos, mas você pode usar qualquer ambiente mencionado nesta seção.

1. Preparar

Prepare seu ambiente para autenticar e executar scripts do Terraform. Além disso, obtenha as informações de que sua conta precisa para autenticar os scripts.

Instalar o Terraform
Este tutorial sugere que você instale a versão mais recente do Terraform suportada pelo OCI Resource Manager. O Resource Manager é um serviço para criar modelos do Terraform para recursos do OCI. Caso você queira usar o Resource Manager com seus scripts do Terraform posteriormente, a versão do Terraform será suportada.
  1. Em seu ambiente, verifique a versão do Terraform. 
    terraform -v
    Se você não tiver a versão do Terraform suportada mais recente, instale a versão suportada mais recente usando as etapas a seguir.
  2. Em um browser, vá para HashiCorp Lista de Versões do Terraform.
  3. Selecione a pasta com a versão do Terraform suportada mais recente.

    Exemplo: terraform_1.5.7

  4. Copie o nome do arquivo zip que corresponde ao seu ambiente em um bloco de notas.

    terraform_<version>_<your_environment>.zip

    Exemplo de ambiente AMD do Oracle 64-bit Linux: terraform_1.5.7_linux_amd64.zip

  5. Em seu ambiente, crie um diretório temporário e passe para esse diretório: 
    mkdir temp
    cd temp
  6. Faça download do arquivo zip do Terraform: 
    wget https://releases.hashicorp.com/terraform/<version>/terraform_<version>_<your_environment>.zip
    Dica

    Você pode construir o URL copiando o endereço do browser. Observe que <version> não inclui a palavra terraform.

    Por exemplo:

    wget https://releases.hashicorp.com/terraform/1.5.7/terraform_1.5.7_linux_amd64.zip

    Se você vir um erro de conexão e estiver na VPN, verifique suas configurações de proxy. Consulte Solução de Problemas.

  7. Descompacte o arquivo. Por exemplo: 
    unzip terraform_1.5.7_linux_amd64.zip
  8. Mova a pasta descompactada para uma pasta que contenha os binários dos aplicativos de terceiros que você instala. Por exemplo, para o Oracle Linux, mova a pasta descompactada para /usr/local/bin: 
    sudo mv terraform /usr/local/bin
  9. Volte ao seu diretório home: 
    cd
  10. Verifique a versão do Terraform: 
    terraform -v

    Exemplo: Terraform v1.5.7 on linux_amd64

    Ignore qualquer mensagem indicando que a versão do Terraform está desatualizada. O importante é usar a versão do Terraform suportada mais recente.

Você instalou o Terraform com sucesso.
Criar Chaves RSA
Você cria chaves RSA para a API acessando sua conta do Oracle Cloud Infrastructure.
Observação

Ignore a criação de chaves RSA se:
  • Você está usando o Cloud Shell ou o Resource Manager. Você já está autenticado quando acessa a Console do Oracle Cloud.
  • Você já criou chaves RSA para o tutorial Configurar Descoberta de Recursos.
  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 scripts do Terraform e copie as informações em um bloco de notas.

  1. Colete o caminho para a chave privada que você adicionou em Criar Chaves RSA.

    Exemplo para o Oracle Linux: /home/opc/.oci/<your-rsa-key-name>.pem

  2. Colete o OCID do usuário, a impressão digital, o OCID da tenancy e a região da chave de API adicionada em Criar Chaves RSA. (Já deve estar no bloco de notas.)
    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. Localize a chave de API que você adicionou em Criar Chaves RSA.
    5. No menu Ações da chave, selecione Exibir arquivo de configuração.

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

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

2. Criar Scripts

Crie scripts para autenticação, para extrair dados da sua conta e imprimir saídas.

Adicionar Autenticação Baseada em Chave de API
Primeiro, configure um diretório para scripts do Terraform. Em seguida, adicione um script de provedor para que sua conta do OCI possa autenticar os scripts executados nesse diretório. Por fim, adicione um script de versões contendo um bloco required_providers para declarar as versões necessárias do provedor.
  1. Em <your-home-directory>, crie um diretório chamado tf-provider e passe para esse diretório. 
    mkdir tf-provider
    cd tf-provider
  2. Crie um arquivo denominado provider.tf.
  3. Adicione o código a seguir a provider.tf: 
    provider "oci" {
  tenancy_ocid = "<tenancy-ocid>"
  user_ocid = "<user-ocid>" 
  private_key_path = "<rsa-private-key-path>"
  fingerprint = "<fingerprint>"
  region = "<region-identifier>"
}
  4. Salve o arquivo provider.tf.
  5. No mesmo diretório, crie um arquivo chamado versions.tf.
  6. Adicione o código a seguir a versions.tf: 
    terraform {
  required_providers {
    oci = {
      source  = "oracle/oci"
      version = ">=4.67.3"
    }
  }
  required_version = ">= 1.0.0"
}
  7. Salve o arquivo versions.tf.
Explicação

Use as seguintes variáveis para autenticação baseada em Chave de API:

  • tenancy_ocid
  • user_ocid
  • private_key_path
  • fingerprint
  • region
Para obter detalhes sobre o provedor Terraform do OCI, consulte
Dica

Não é necessário instalar o provedor. O provedor é baixado quando você executa os scripts neste tutorial.
Adicionar uma Origem de Dados
Nesta seção, você extrai uma lista dos domínios de disponibilidade em sua tenancy. Ao extrair dados, você confirma que sua conta do OCI autentica seu script provider.tf e obtém informações da sua conta.
  1. No diretório tf-provider, crie um arquivo chamado availability-domains.tf.
    Importante

    Certifique-se de que todos os arquivos *.tf estejam no mesmo diretório. O Terraform processa todos os arquivos em um diretório na ordem correta, com base em seu relacionamento. (Para uma abordagem modular e reutilização futura, coloque as informações do provedor em um arquivo separado de outros scripts.)
  2. Adicione o código a seguir a availability-domains.tf, substituindo o campo por colchetes, por informações de Reunir Informações Necessárias. 
    # Source from https://registry.terraform.io/providers/oracle/oci/latest/docs/data-sources/identity_availability_domains

# Tenancy is the root or parent to all compartments.
# For this tutorial, use the value of <tenancy-ocid> for the compartment OCID.

data "oci_identity_availability_domains" "ads" {
  compartment_id = "<tenancy-ocid>"
}
    Observação

    A origem de dados obtém uma lista de domínios de disponibilidade em toda a sua tenancy. A tenancy é o OCID do compartimento para o compartimento raiz. Fornecer um "<compartment-ocid>" específico ou o "<tenancy-ocid>" gera a mesma lista.
Explicação

No Terraform, para extrair dados, você usa uma origem de dados. A extração de dados de uma origem de dados é semelhante ao método GET em APIs REST.

  • Vá para Provedor do Oracle Cloud Infrastructure.
  • Na caixa Filtro no canto superior esquerdo, digite availability domains.
  • Em Identidade, vá para Origens de Dados e selecione oci_identity_availability_domains.

    O título da página é o tipo de recurso: oci_identity_availability_domains

  • Localize o nome da Origem de Dados no título da página:
    • Origem de Dados:
  • Na seção Referência de Argumento, localize todos os argumentos (entradas) identificados como (Necessário):
    • compartment_id
  • Construa um bloco de origem de dados:
    • Declarar uma origem de dados com a palavra-chave: data.
    • Adicione um label para o nome da origem de dados: "oci_identity_availability_domains"
    • Adicione um label de sua escolha para o nome local:
      • O label pode conter letras, dígitos, sublinhados (_) e hifens (-). O primeiro caractere não deve ser um dígito.
      • Este tutorial usa o nome local, "ads", para construir data "oci_identity_availability_domains" "ads".
    • Dentro do bloco de código, forneça valores para todos os argumentos obrigatórios.
      • Exemplo: compartment_id = "<some-compartment-ocid>"
    • Para argumentos opcionais, forneça valores para restringir os resultados da extração. Somente algumas origens de dados têm argumentos opcionais.
Adicionar Saídas

A origem de dados oci_identity_availability_domains extrai uma lista de domínios de disponibilidade. Nesta seção, você declara um bloco de saída para imprimir as informações extraídas.

  1. No diretório tf-provider, crie um arquivo chamado outputs.tf.
  2. Adicione o código a seguir a outputs.tf. 
    # Output the "list" of all availability domains.
output "all-availability-domains-in-your-tenancy" {
  value = data.oci_identity_availability_domains.ads.availability_domains
}
  3. Salve o arquivo outputs.tf.
    Importante

    Certifique-se de que todos os arquivos *.tf estejam no mesmo diretório. O Terraform processa todos os arquivos em um diretório na ordem correta, com base em seu relacionamento.
Explicação
  • Vá para Referência de Atributos (oci_identity_availability_domains).
    Observação

    Os atributos são as saídas que você pode retornar para a origem de dados oci_identity_availability_domains.
  • Encontre os atributos:
    • Atributo: availability_domains:
      • A lista de domínios de disponibilidade
      • Se você gerar availability_domains:, obterão três atributos para cada domínio de disponibilidade na lista:
        • compartment_id
        • id
        • nome
  • Construa um bloco de saída da origem de dados:
    • Declarar um bloco de saída com a palavra-chave: output
    • Adicione um rótulo a ser impresso com os resultados de saída:
      • O label pode conter letras, dígitos, sublinhados (_) e hifens (-). O primeiro caractere não deve ser um dígito.
      • Exemplo: "all-availability-domains-in-your-tenancy"
    • Dentro do bloco de código, informe um valor para a saída da origem de dados com a expressão:
      • value = data.<data-source-name>.<local-name-for-data-source>.<attribute>
      • Exemplo: value = data.oci_identity_availability_domains.ads.availability_domains

3. Executar Scripts

Execute seus scripts do Terraform. Depois que sua conta autentica os scripts, o Terraform extrai os domínios de disponibilidade da sua tenancy.

Inicializar
Inicialize um diretório de trabalho no diretório tf-provider.
  1. Execute o comando init do Terraform. 
    terraform init

    Exemplo de saída:

    Initializing the backend...

Initializing provider plugins...

Terraform has been successfully initialized!

    Se você vir um erro de conexão ou um erro de "falha ao consultar" e estiver na VPN, verifique suas configurações de proxy. Consulte Solução de Problemas.

  2. Verifique o conteúdo do diretório tf-provider. 
    ls -a

Agora você tem uma pasta chamada .terraform que inclui os plug-ins do provedor oci.

Plano
Crie um plano de execução para verificar se as alterações mostradas no plano de execução correspondem às suas expectativas, sem alterar os recursos reais.
Execute o comando plan do Terraform. 
terraform plan

Exemplo de saída:

data.oci_identity_availability_domains.ads: Reading...
data.oci_identity_availability_domains.ads: Read complete after 1s [id=xxx]

Changes to Outputs:
  + all-availability-domains-in-your-tenancy = [
      + {
          + compartment_id = "ocid1.tenancy.oc1..xxx"
          + id             = "ocid1.availabilitydomain.xxx"
          + name           = "QnsC:US-ASHBURN-AD-1"
        },
      + {
          + compartment_id = "ocid1.tenancy.oc1..xxx"
          + id             = "ocid1.availabilitydomain.yyy"
          + name           = "QnsC:US-ASHBURN-AD-2"
        },
      + {
          + compartment_id = "ocid1.tenancy.oc1..xxx"
          + id             = "ocid1.availabilitydomain.zzz"
          + name           = "QnsC:US-ASHBURN-AD-3"
        },
    ]

You can apply this plan to save these new output values to the Terraform state, without changing any real
infrastructure.
Observação

  • Você está extraindo dados, então o plano mostra que você só está adicionando saídas. Você não está adicionando, alterando ou destruindo nenhum recurso.
  • Você está usando o arquivo output.tf em vez da opção -out, para que possa ignorar a seguinte mensagem:
    Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform
apply" now.
Aplicação
  1. Execute os scripts do Terraform e obtenha as saídas: 
    terraform apply
  2. Quando for solicitada a confirmação, digite yes.

    Depois que você executar o comando apply, a saída será exibida no terminal.

    Exemplo de saída:
    Apply complete! Resources: 0 added, 0 changed, 0 destroyed.

Outputs:

all-availability-domains-in-your-tenancy = tolist([
  {
    "compartment_id" = "ocid1.tenancy.xxx"
    "id" = "ocid1.availabilitydomain.xxx"
    "name" = "QnsC:US-ASHBURN-AD-1"
  },
  {
    "compartment_id" = "ocid1.tenancy.xxx"
    "id" = "ocid1.availabilitydomain.xxx"
    "name" = "QnsC:US-ASHBURN-AD-2"
  },
  {
    "compartment_id" = "ocid1.tenancy.xxx"
    "id" = "ocid1.availabilitydomain.xxx"
    "name" = "QnsC:US-ASHBURN-AD-3"
  },
])

Parabéns! Sua conta do Oracle Cloud Infrastructure agora pode autenticar seus scripts do provedor do Oracle Cloud Infrastructure Terraform.

Referências:

Diagnóstico e Solução de Problemas

Você pode encontrar as mensagens de erro a seguir ao executar seus scripts do Terraform.

Erros 401 - (Service error:NotAuthenticated)

Uma das seguintes variáveis tem um valor incorreto:

  • OCID da Tenancy
  • OCID do Usuário
  • Impressão Digital
  • Chave privada RSA (o caminho ou a chave)
  1. No arquivo provider.tf, verifique novamente os nomes das variáveis e seus valores. 
    provider "oci" {
  tenancy_ocid = "<tenancy-ocid>"
  user_ocid = "<user-ocid>" 
  private_key_path = "<rsa-private-key-path>"
  fingerprint = "<fingerprint>"
  region = "<region-identifier>"
}
  2. Atualize as variáveis ou seus valores, conforme necessário.
  3. Certifique-se de ter adicionado aspas em torno dos valores de string.
  4. Execute os scripts.

Não é possível criar o cliente; configuração inválida: não foi encontrada uma configuração adequada para a chave privada

Os scripts do Terraform não podem localizar a chave privada RSA.

  1. Repita as etapas para criar chaves RSA e use a chave atualizada.
  2. Certifique-se de que, no arquivo provider.tf, a variável que descreve o RSA seja chamada private_key_path.
    private_key_path = "<rsa-private-key-path>"
  3. Certifique-se de que o caminho para a chave privada RSA no arquivo provider.tf esteja correto. Por exemplo, certifique-se de que o caminho comece com uma barra e tenha o nome correto para a chave privada, <your-rsa-key-name>.pem
  4. Remova as variáveis de ambiente do <rsa-private-key-path>.

    Por exemplo, no arquivo provider.tf, em vez de $HOME/.oci/<rsa-private-key-path>, use /home/opc/<rsa-private-key-path>.

    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.

Esse host não está presente.

O identificador de região tem um valor incorreto.

  1. Na barra de navegação da Console, localize sua região.
    Consulte Como Trabalhar em Regiões.
  2. Na tabela em Regiões e Domínios de Disponibilidade, localize o <region-identifier> da sua região. Exemplo: us-ashburn-1.
  3. No arquivo provider.tf, atualize o valor de <region-identifier> e tente novamente.

Falha ao consultar pacotes de provedores disponíveis

Se você estiver em uma VPN, verifique as configurações de proxy.

  1. Desconectar da VPN.
  2. Conecte-se à sua VM ou ao seu ambiente sem a VPN e execute os scripts do Terraform a seguir. 
    terraform init
terraform plan
terraform apply
    Se você não receber uma mensagem de erro, as configurações de proxy da VPN estão causando o erro.
  3. Consulte o administrador, atualize as configurações de proxy e tente novamente.