Documentação do Oracle Cloud Infrastructure

Usando a Descoberta de Recursos

A descoberta de recursos do provedor Terraform do Oracle Cloud Infrastructure (OCI) usa o terraform-exec do HashiCorp para importar os recursos descobertos do OCI para os arquivos de estado e de configuração do Terraform.

Pré-requisitos

O Terraform -exec exige que a CLI do Terraform esteja presente no seu sistema. Consulte Fazer Download e Instalar o Terraform para obter detalhes da instalação.

Observação

Se você estiver usando o Terraform versão v0.11, esta ferramenta não poderá gerar um arquivo de estado. Somente configurações são suportadas na v0.11. Por padrão, as configurações são geradas na v0.12.

Se você usar a v0.13.* da CLI do Terraform, verifique se a versão é compatível com a sintaxe da v0.12.

Além disso, você deve ter o provedor Terraform do OCI baixado e instalado. Consulte Fazer Download e Instalar o Provedor para obter instruções de download.

Adicionando as Ferramentas ao Caminho

Para executar o provedor Terraform do OCI como executável e usar a descoberta de recursos, você pode fazer o seguinte:

  • Adicione terraform-provider-oci ao caminho do sistema.
  • Execute o provedor no diretório em que ele está localizado.
  • Especifique o caminho completo para o provedor ao executar comandos de descoberta de recursos.

Como os comandos de descoberta de recursos usam terraform-exec para chamar o Terraform em seu nome, seu sistema deve especificar a localização da CLI do Terraform usando um dos seguintes métodos:

  • Informe o caminho completo, incluindo o nome da CLI do Terraform, usando a variável de ambiente terraform_bin_path. Consulte Variáveis de Ambiente para obter mais informações sobre como definir variáveis.
  • Adicione a CLI do Terraform ao caminho do sistema.

Autenticação

Para descobrir recursos no seu compartimento, o provedor Terraform do OCI precisa de informações de autenticação sobre o usuário, a tenancy e a região com os quais descobrir os recursos. É recomendável especificar um usuário que tenha acesso para inspecionar e ler os recursos a serem descobertos.

Você pode usar a Autenticação de Chave de API e Variáveis de Ambiente ou a Autorização do Controlador de Instâncias para fornecer as informações necessárias.

Exportando Recursos

Depois de ter especificado o local da CLI do Terraform e as definições de autenticação, um dos seguintes comandos poderá ser usado para exportar os recursos de um compartimento:

terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path>

Esses comandos descobrem todos os recursos suportados no compartimento e geram arquivos de configuração do Terraform no output_path fornecido. Os arquivos .tf gerados contêm a configuração do Terraform com os recursos descobertos pelo comando.

Cuidado

Certifique-se de que output_path esteja vazio antes de executar a descoberta de recursos.
Observação

O parâmetro compartment_id será obrigatório caso esteja sendo usada a Autorização do Controlador de Instâncias.

As seguintes combinações de parâmetros comuns exportam os recursos descritos:

  • compartment_id=<empty_or_tenancy_OCID> services=<empty_or_not_specified> - Todos os recursos com escopo na tenancy e no compartimento.
  • compartment_id=<empty_or_tenancy_OCID> services=<comma_seperated_list> - Recursos com escopo na tenancy e no compartimento para os serviços especificados.
  • compartment_id=<non-root_OCID> services=<empty_or_not_specified> - Todos os recursos com escopo no compartimento.
  • compartment_id=<non-root_OCID> services=<comma_seperated_list> - Recursos com escopo no compartimento para os serviços especificados. Os recursos com escopo na tenancy não serão descobertos mesmo que os serviços com esses recursos sejam especificados.
Observação

A exportação de recursos do compartimento só suporta o compartimento de destino.. Os recursos em compartimentos filhos não são descobertos.

Parâmetros

Você pode usar os seguintes parâmetros para controlar o comportamento da ferramenta de descoberta de recursos.

Parâmetro Detalhes
command O comando a ser executado. Os comandos suportados incluem:
  • export - descobre os recursos do OCI no compartimento e gera arquivos de configuração do Terraform para eles
  • list_export_resources - lista os tipos de recurso do OCI do Terraform descobertos pelo comando export
  • list_export_services - lista os valores permitidos para argumentos de serviços com o escopo no formato JSON
compartment_id O OCID do compartimento a ser exportado. Se compartment_id ou compartment_name não for especificado, o compartimento raiz será usado. Obrigatório se estiver usando a Autorização de Controlador de Instâncias.
compartmet_name O nome de um compartimento a ser exportado. Se compartment_id ou compartment_name não for especificado, o compartimento raiz será usado.
exclude_services Uma lista separada por vírgulas de recursos de serviço a serem excluídos da exportação. Qualquer serviço presente nos argumentos services e exclude_services é excluído.
filter Filtre recursos descobertos por critérios especificados. Para obter mais informações, consulte Filtrando Recursos.
generate_state Forneça este flag para importar os recursos descobertos para um arquivo de estado, além dos arquivos de configuração do Terraform.
ids Uma lista separada por vírgulas de tuplas <resource_type:resource_ID> (por exemplo, oci_core_instance:ocid.....) para recursos a serem exportados. O ID pode ser um OCID ou um ID de importação do Terraform. Por padrão, todos os recursos são exportados.
list_export_services_path O caminho completo, incluindo o nome do arquivo, a ser usado como saída para a lista de serviços suportados, no formato JSON.
output_path O caminho absoluto para produzir as configurações geradas e os arquivos de estado do compartimento exportado.
parallelism O número de threads para descobrir recursos em paralelo. O valor padrão é 1.
retry_timeout A duração em segundos durante a qual as chamadas de API aguardam e repetem a operação em caso de erros de API. Por padrão, a duração do timeout de repetição é de 15 segundos.
services Uma lista separada por vírgulas de recursos de serviço a serem exportados. If not specified, all resources within the provided compartment (excluding IAM resources) are exported.

Consulte Serviços Suportados para obter os valores aceitos e Exportando Recursos de Identidade para obter as informações relacionadas.
tf_version A versão da sintaxe do Terraform a ser usada ao gerar arquivos de configuração. O padrão é v0.12. Os valores permitidos são:
  • 0.11
  • 0.12

Se você especificar 0.11 como versão da sintaxe, use a v0.11 da CLI do Terraform para descobrir recursos.

Se você usar o Terraform CLI v0.13 e superior para descobrir recursos, verifique se a versão é compatível com a sintaxe da v0.12.

Os arquivos de estado são gerados na sintaxe do Terraform que corresponde à versão da CLI do Terraform usada para descobrir recursos. O parâmetro tf_version não se aplica a arquivos de estado.
variables_global_level

Liste os atributos de nível superior a serem exportados como variáveis, seguindo o formato attribute1,attribute2. Os atributos no nível do recurso (variables_resource_level) são excluídos desta lista.
variables_resource_level

Liste os atributos no nível do recurso a serem exportados como variáveis, seguindo o formato resourceType.attribute. Os atributos de nível superior (variables_global_level) são excluídos desta lista.

Filtrando Recursos

Filtre recursos descobertos por critérios especificados:

  • Filtro de tipo de recurso: Type<operator><provider-resource-type>

    <operator> é = (igual a) ou != (diferente de)

  • Filtro de atributo: AttrName=<attribute-name>;Value<operator><value> Localize todos os recursos com atributo e valor correspondentes
  • Até 10 filtros (os recursos devem atender a todos)
Filtro de tipo de recurso: somente VCN
--filter="Type=oci_core_vcn"
Filtro de tipo de recurso: Qualquer coisa, exceto VCN
--filter="Type!=oci_core_vcn"
Filtro de atributo: Valor de tag definido
--filter="AttrName=defined_tags.example-namespace.example-key;Value=example-value"
Vários filtros: Somente VCN, deve ter o atributo dns_label definido para testar
--filter="Type=oci_core_vcn" --filter="AttrName=dns_label;Value=test"

Para obter mais informações sobre como filtrar recursos descobertos, consulte Filtrando Recursos descobertos por meio da Descoberta de Recursos.

Registro em Log Detalhado

Para obter uma saída detalhada da console quando o provedor estiver em execução, preceda o comando de descoberta de recursos com os flags TF_LOG ou OCI_TF_LOG. Por exemplo:

TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>
OCI_TF_LOG=DEBUG terraform-provider-oci -command=export -compartment_name=<compartment_name> -output_path=<output_path>

O nível TF_LOG e os flags OCI_TF_LOG também podem ser definidos como variáveis de ambiente.

Para redirecionar a saída detalhada da console para um arquivo de log, defina a variável de ambiente OCI_TF_LOG_PATH e forneça o caminho.

Status de Saída

Para qualquer erro relacionado às APIs do OCI ou indisponibilidade de serviço ao descobrir recursos, a ferramenta passa a localizar o próximo recurso. Todos os erros encontrados são exibidos após a conclusão da descoberta.

  • Código de saída 0 - Sucesso.
  • Código de saída 1 - Falha por causa de erros, como variáveis de ambiente, argumentos ou configuração incorretos.
  • Código de saída 64 - Sucesso parcial. A descoberta de recursos não foi pôde localizar todos os recursos por causa de falhas no serviço.

Exportando Recursos de Identidade

Alguns recursos, como aqueles de identidade, só existem no nível da tenancy e não podem ser descobertos em um compartimento específico. Para descobrir esses recursos, use o seguinte comando, que omite qualquer parâmetro de compartimento:
terraform-provider-oci -command=export -output_path=<output_path> -services=identity
Observação

Ao exportar recursos de identidade, o valor compartment_id, se fornecido, será ignorado.

Exportando Recursos para Outro Compartimento

Depois de revisar os arquivos de configuração gerados do Terraform e fazer as alterações necessárias, a configuração poderá ser usada com o Terraform. Um caso de uso desse tipo seria a reimplantação desses recursos em um novo compartimento ou tenancy, usando o Terraform.

Para isso, especifique as seguintes variáveis de ambiente:

export TF_VAR_tenancy_ocid=<target_tenancy_OCID>
export TF_VAR_compartment_ocid=<target_compartment_OCID>

Em seguida, execute o seguinte comando:

terraform apply

Gerando um Arquivo de Estado do Terraform

Cuidado

O arquivo de estado contém todos os atributos de recursos que são especificados como parte dos arquivos de configuração. Se você gerenciar dados sigilosos com o Terraform, como senhas de banco de dados ou de usuário ou chaves privadas de instâncias, trate o próprio arquivo de estado como dados sigilosos. Consulte Armazenando Dados Sigilosos para obter mais informações.

Também é possível gerar um arquivo de estado do Terraform para gerenciar os recursos descobertos. Para fazer isso, execute o seguinte comando, que inclui o flag -generate_state:

terraform-provider-oci -command=export -compartment_id=<compartment_OCID> -output_path=<output_path> -generate_state

Os resultados desse comando são os arquivos .tf que representam a configuração do Terraform e um arquivo terraform.tfstate que representa o estado. Consulte Estado para obter mais informações.

Observação

O arquivo de estado do Terraform gerado por esse comando só é compatível com o Terraform v0.12.4 e mais recente.