Documentação do Oracle Cloud Infrastructure

Trabalhando com Inventário do Ansible

O Ansible rastreia os recursos da configuração preservando listas, chamadas listas do inventário, como arquivos simples (também chamados às vezes de arquivo host). Essas listas de inventário podem ser estáticas ou dinâmicas. As listas dinâmicas podem ser atualizadas automaticamente quando recursos de inventário são adicionados, excluídos ou movidos.

Como muitos recursos da Oracle Cloud Infrastructure (OCI) são adicionados e excluídos com o passar do tempo, as listas de estoque estático podem se tornar facilmente obsoletas. Ferramentas como o Terraform ou os SDKs do OCI também podem afetar seus recursos.

O Oracle Cloud Infrastructure fornece um plug-in de inventário dinâmico para manter o inventário preciso do Ansible.

Para obter mais informações sobre arquivos de inventário do Ansible, consulte Trabalhando com Inventário e Trabalhando com Inventário Dinâmico.

Ativando o Plug-in de Inventário

Se você tiver um arquivo ansible.cfg existente e essa configuração já ativar os plug-ins usando enable_plugins, ative o plug-in de inventário do OCI adicionando-o também. Por exemplo:

[inventory]
enable_plugins = oracle.oci.oci

Se você não tiver ainda um arquivo ansible.cfg que contenha enable_plugins, não precisará adicionar o plug-in de inventário do OCI à configuração.

Configurando o Plug-in de Inventário

O único requisito para usar o plug-in de inventário do OCI após sua ativação é fornecer uma origem de inventário que você tem permissões para analisar. As origens de inventário são definidas em um arquivo de configuração do YAML. Consulte Permissões do Usuário para obter mais informações.

Para começar a usar o plug-in de inventário com uma origem de configuração do YAML, crie um arquivo com um dos seguintes nomes de arquivo aceitos:

  • <filename>. oci.yml
  • <filename>. oci.yaml

Adicione plugin: oracle.oci.oci ao arquivo de configuração do YAML.

O arquivo de origem de inventário mínimo necessário para executar o plug-in de inventário do OCI tem a seguinte aparência, por exemplo:

# demo.oci.yml
plugin: oracle.oci.oci
 
# Optional fields to specify oci connection config:
config_file: ~/.oci/config
config_profile: DEFAULT

Este exemplo usa os parâmetros config_file e config_profile para que o plug-in possa usar as informações de autenticação descritas no Arquivo de Configuração do SDK e da CLI. Alguns parâmetros também podem ser fornecidos como variáveis de ambiente.

Para obter uma lista completa de parâmetros e variáveis de ambiente que o plug-in suporta, consulte Plug-in de Inventário do OCI. Os cenários de inventário incluem muitos dos parâmetros disponíveis.

Importante

Por padrão, o plug-in de inventário da OCI descobre e lista apenas instâncias de computação com um endereço IP público. Consulte Preferências de Formato de Nome de Host para obter mais informações.

Ordem de Precedência

O plug-in de inventário usa a seguinte ordem de precedência quando uma opção é fornecida em mais de um local:

  1. Definições de arquivo YAML.
  2. Variáveis de ambiente.
  3. Configurações no profile selecionado no seu arquivo de configurações do OCI.

Extraindo Hosts de Banco de Dados

Por padrão, o plug-in de inventário do OCI só descobre e lista instâncias de computação. Os nós do banco de dados são servidores que executam software de banco de dados. Os nós de banco de dados são extraídos definindo a opção fetch_db_hosts como true. Por exemplo:

# demo.oci.yml

# DB Hosts
plugin: oracle.oci.oci
fetch_db_hosts: true

Usando o Plug-in de Inventário

Os plug-ins de inventário do Ansible permitem definir as origens de dados usadas para compilar um inventário de hosts que o Ansible usa para direcionar tarefas. Essas origens de dados são acessadas usando os parâmetros da linha de comando -i /path/to/file ou -i 'host1, host2' ou de outras origens de configuração.

Você pode executar o inventário com este comando, por exemplo:

ansible-inventory -i <filename>.oci.yml --graph

Isso produz resultados semelhantes a este:

@all:
  |--@oci:
  |  |--compute_instance1
  |  |--compute_instance2
  |–@ungrouped:
Importante

Por padrão, o inventário é gerado para todos os compartimentos da tenancy. Você deve ter a permissão COMPARTMENT_INSPECT no compartimento raiz desse script para poder acessar todos os compartimentos. Porém, quando compartment_ocid é especificado, o inventário só é gerado para o compartimento em questão; portanto, você só precisa da permissão COMPARTMENT_INSPECT no compartimento especificado. Para obter mais informações, consulte Como as Políticas Funcionam.

Para extrair todos os detalhes da instância, você também deve ter permissão para listar e ler instâncias e VNICs, bem como ler VCNs e sub-redes. Consulte Permissões do Usuário para obter mais informações.

Você pode adicionar plug-ins de inventário ao caminho do plug-in e definir o caminho padrão do inventário para simplificar comandos. Adicione o caminho de inventário padrão à seção [defaults] do seu arquivo ansible.cfg ou use a variável de ambiente ANSIBLE_INVENTORY para apontar suas origens de inventário. Em seguida, você pode executar o seguinte comando para gerar o mesmo resultado de quando transmite suas origens de configuração de YAML diretamente:

ansible-inventory --graph

Os plug-ins de inventário normalmente só são executados no início de uma execução, antes de playbooks, execuções e atribuições serem carregados. Você pode 'reexecutar' um plug-in usando a tarefa meta: refresh_inventory, que limpa o inventário existente e o recria.

Resultado do Inventário

A lista de inventário gerada pelo plug-in de inventário é agrupada usando os seguintes atributos:

  • A região na qual a instância de computação reside
  • O nome do compartimento ao qual a instância de computação pertence
  • O Domínio de Disponibilidade em que a instância de computação está
  • O vcn_id da VCN em que está a instância de computação
  • O subnet_id da sub-rede na qual está a instância de computação
  • O security_list_ids da sub-rede na qual está a instância de computação
  • O image_id da imagem usada para iniciar a instância de computação
  • Forma da instância de computação
  • As tags de formato livre da instância de computação, com o nome do grupo definido como tag_<tag_name>=<tag_value>
  • As tags definidas da instância de computação, com o nome do grupo definido como <tag_namespace>#<tag_name>=<tag_value>
  • Metadados de instância de computação da OCI (pares de chave/valor), com o nome do grupo definido como <metadata-key>=<metadata-value>
  • Metadados estendidos do OCI Compute Instance (pares de chave/valor), com o nome do grupo definido como <metadata-key>=<metadata-value>

Preferências de Formato de Nome de Host

O inventário gerado pelo plug-in de inventário do OCI contém apenas instâncias que têm um endereço IP público por padrão. Isso é útil nos casos em que o nó do controlador do Ansible está fora da VCN, pois o Ansible só consegue acessar instâncias que tenham endereços IP públicos.

Você pode configurar inventory_hostname como private_ip ou como qualquer nome de host personalizado especificando expressões Jinja2 como lista para a opção hostname_format_preferences. A opção hostname_format_preferences usa uma lista de expressões Jinja2 em ordem de precedência para compor inventory_hostname. O plug-in de inventário ignora expressões quando o resultado é uma string vazia ou um valor "None". A instância será ignorada se nenhuma das expressões hostname_format_preferences resultar em um valor não vazio.

O exemplo a seguir define inventory_hostname como "display_name+'.oci.com'" ou "private_ip" ou "public_ip":

hostname_format_preferences:
  - "display_name+'.oci.com'"
  - "private_ip"
  - "public_ip"

As expressões são avaliadas no host_vars de cada instância. A avaliação respeita a ordem de precedência na configuração para compor inventory_hostname. No exemplo anterior, "display_name+'.oci.com'" é avaliado antes de "private_ip" e "public_ip".

Filtrando Hosts

O plug-in de inventário do OCI vem com várias opções de filtragem para filtrar os hosts retornados pelo plug-in.

Excluir Hosts do Inventário

Você pode informar uma lista de expressões condicionais Jinja2 para o parâmetro exclude_host_filters. Cada expressão na lista é avaliada para cada host. Quando a expressão é verdadeira, o host é excluído do inventário. O parâmetro exclude_host_filters tem prioridade sobre as opções include_host_filters e filters.

O exemplo a seguir exclui hosts que não estão na região 'iad' do inventário:

exclude_host_filters:
  - "region not in ['iad']"

Excluir Hosts Usando Tags de Formato Livre

Para excluir um host do inventário usando tags de formato livre, você pode usar a seguinte sintaxe:

exclude_host_filters:
  # filter the hosts with freeform tag with key <tag_key> which has value <tag_value>
  - "'<tag_value>' == freeform_tags.<tag_key>"
  # filter the hosts which has <tag_key> freeform tag
  - "'<tag_key>' in freefrom_tags"

Por exemplo:

exclude_host_filters:
  - "'operating_system' in freeform_tags"
  - "'linux' == freeform_tags.operating_system"

Excluir Hosts Usando Tags Definidas

Para excluir um host do inventário usando tags definidas, você pode usar a seguinte sintaxe:

exclude_host_filters:
  #filter the hosts with defined tag in <namespace> with <tag_key> and <tag_value>
  - "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  # filter the hosts with <tag_key> in the <namespace> in defined tags
  - "'<tag_key>' in defined_tags.<namespace>"

Por exemplo:

exclude_host_filters:
  - "'ansible' == defined_tags.ansible_collections_tag_namespace.managed_by"
  - "'managed_by' in defined_tags.ansible_collections_tag_namespace"

Incluir Hosts no Inventário

Você pode informar uma lista de expressões condicionais Jinja2 para o parâmetro include_host_filters. Cada expressão na lista é avaliada para cada host. Quando a expressão é verdadeira, o host é incluído no inventário.

O exemplo a seguir inclui somente os hosts que têm um display_name que termina com '.oci.com' no inventário:

include_host_filters:
  - "display_name is match('.*.oci.com')"
Observação

As opções include_host_filters e filters não podem ser usadas juntas.

Incluir Hosts Usando Tags de Formato Livre

Para incluir um host no inventário usando tags de formato livre, você pode usar a seguinte sintaxe:

include_host_filters:
  # filter the hosts with freeform tag with key <tag_key> which has value <tag_value>
  - "'<tag_value>' == freeform_tags.<tag_key>"
  # filter the hosts which has <tag_key> freeform tag
  - "'<tag_key>' in freefrom_tags"

Por exemplo:

include_host_filters:
  - "'operating_system' in freeform_tags"
  - "'linux' == freeform_tags.operating_system"

Incluir Hosts Usando Tags Definidas

Para incluir um host no inventário usando tags definidas, você pode usar a seguinte sintaxe:

include_host_filters:
  #filter the hosts with defined tag in <namespace> with <tag_key> and <tag_value>
  - "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  # filter the hosts with <tag_key> in the <namespace> in defined tags
  - "'<tag_key>' in defined_tags.<namespace>"

Por exemplo:

include_host_filters:
  -  "'ansible' == defined_tags.ansible_collections_tag_namespace.managed_by"
  -  "'managed_by' in defined_tags.ansible_collections_tag_namespace"

Ativando o Cache

O armazenamento no cache pode ser ativado para acelerar pesquisas. É possível definir opções de armazenamento em cache para uma origem de configuração YAML individual ou para várias origens de inventário usando variáveis de ambiente ou arquivos de configuração do Ansible. Se você ativar o armazenamento no cache para um plug-in de inventário sem fornecer opções de armazenamento no cache específicas do inventário, o plug-in de inventário usará opções de armazenamento no cache de fatos.

Este é um exemplo de ativação do armazenamento no cache para um arquivo de configuração YAML individual:

# demo.oci.yml
plugin: oracle.oci.oci
cache: yes
cache_plugin: jsonfile
cache_timeout: 7200
cache_connection: /tmp/oci_inventory
cache_prefix: oci

Usando Grupos Dinâmicos

Você pode criar grupos dinâmicos usando variáveis de host com a opção keyed_groups construída. A opção groups também pode ser usada para criar grupos e criar e modificar variáveis de host. A sintaxe para grupos com chaves e grupos que usam tags é a seguinte:

keyed_groups
- key: freeform_tags.<tag key>
  prefix: <my_prefix>
- key: defined_tags.<namespace>.<tag key>
  prefix: <my_prefix>

groups:
  <group_name>: "'<tag_value>' == freeform_tags.<tag_key>"
  <group_name>: "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  <group_name>: "'<tag_key>' in defined_tags.<namespace>"

Por exemplo: 

# demo.oci.yml
plugin: oracle.oci.oci
regions:
  - us-phoenix-1
  - us-ashburn-1
keyed_groups:
  # add hosts to tag_Name_value groups for each oci host's tags.Name variable
  - key: tags.Name
    prefix: tag_Name_
groups:
  # add hosts to the group development if any of the dictionary's keys or values is the word 'devel'
  development: "'devel' in (tags|list)"
  # add hosts with freefrom_tags that has 'operating_system' key and 'linux' value to 'linux' group
  linux: "'linux' == freeform_tags.operating_system"
  # add hosts with freefrom tags that has 'operating_system' key to os group
  os: "'operating_system' in freeform_tags"
  # add hosts with defined tags in the namespace 'ansible_collections_tag_namespace' with tag 'managed_by' and value 'ansible'
  ansible_managed: "'ansible' == defined_tags.ansible_collections_tag_namespace.managed_by"
  # add hosts with defined tags in the namespace 'ansible_collections_tag_namespace' with tag 'managed_by'
  cm_managed_hosts: "'managed_by' in defined_tags.ansible_collections_tag_namespace"

Este exemplo produz saída semelhante à seguinte: 

@all:
  |--@development:
  |  |--compute_instance1
  |  |--compute_instance2
  |--@linux:
  |  |--compute_instance1
  |--@os:
  |  |--compute_instance1
  |  |--compute_instance2
  |--@ansible_managed:
  |  |--compute_instance1
  |--@cm_managed_hosts:
  |  |--compute_instance2
  |--@ungrouped

Se um host não tiver as variáveis especificadas na configuração, ele não será adicionado a grupos que não sejam aqueles que o plug-in de inventário cria e a variável de host ansible_host não será modificada.

Cenários de Inventário

As seções a seguir incluem exemplos de configuração que abrangem cenários comuns de inventário.

Extrair Todos os Hosts de Computação

Para extrair todos os hosts, sua configuração pode ser tão simples quanto o seguinte exemplo:

plugin: oracle.oci.oci

Extrair Somente Hosts de Banco de Dados

Para extrair todos os nós que hospedam software de banco de dados ao excluir hosts do serviço Compute, sua configuração seria semelhante ao seguinte exemplo:

plugin: oracle.oci.oci

# fetch databse hosts
fetch_db_hosts: true
# don't fetch Compute hosts
fetch_compute_hosts: False

Extrair Hosts de Regiões Específicas

Para extrair hosts apenas em regiões especificadas, sua configuração seria semelhante ao seguinte exemplo:

plugin: oracle.oci.oci

# Fetch only the hosts in the regions us-ashburn-1, us-phoenix-1
regions:
  - us-ashburn-1
  - us-phoenix-1

Definir Nome de Host de Inventário

Para definir o formato de nome de host de inventário usado no inventário, sua configuração incluiria uma seção semelhante ao seguinte exemplo:

plugin: oracle.oci.oci

# Sets the inventory_hostname to either "display_name+'.oci.com'", "public_ip", "private_ip", or "id" 
# "display_name+'.oci.com'" has more preference than "public_ip", "private_ip", "id".
hostname_format_preferences:
  - "display_name+'.oci.com'"
  - "public_ip"
  - "private_ip"
  - "id"

Consulte Preferências de Formato de Nome de Host para obter mais informações.

Excluir Hosts do Inventário

Para usar uma expressão condicional Jinja2 para excluir hosts do inventário, sua configuração incluiria uma seção semelhante ao seguinte exemplo:

plugin: oracle.oci.oci

# Excludes hosts that are not in the region 'iad' from the inventory
exclude_host_filters:
  - "region not in ['iad']"

Consulte Filtrando Dados para obter mais informações.

Incluir Hosts no Inventário

Para usar uma expressão condicional Jinja2 para incluir hosts no inventário, sua configuração incluiria uma seção semelhante ao seguinte exemplo:

plugin: oracle.oci.oci

# Includes only the hosts that have a display_name ending with '.oci.com' in the inventory
include_host_filters:
  - "display_name is match('.*.oci.com')"

Consulte Filtrando Dados para obter mais informações.

Observação

As opções include_host_filters e filters não podem ser usadas juntas.

Extrair Hosts de Compartimentos Específicos

O exemplo a seguir mostra como extrair todos os hosts dos compartimentos especificados:

# Fetch all hosts
plugin: oracle.oci.oci

# Select compartment by OCID or name
compartments:
  - compartment_ocid: <ocid1.compartment.oc1..exampleuniqueID>
    fetch_hosts_from_subcompartments: false

  - compartment_name: "<compartment_name>"
    parent_compartment_ocid: <ocid1.tenancy.oc1..exampleuniqueID>

Outras Opções

O seguinte exemplo de configuração combina os cenários anteriores com mais opções de configuração:

# Fetch all hosts
plugin: oracle.oci.oci

# Optional fields:
config_file: ~/.oci/config
config_profile: DEFAULT

# Example select regions
regions:
  - us-ashburn-1
  - us-phoenix-1

# Enable threads to speedup lookup
enable_parallel_processing: yes

# Select compartment by ocid or name
compartments:
  - compartment_ocid: <ocid1.compartment.oc1..exampleuniqueID>
    fetch_hosts_from_subcompartments: false

  - compartment_name: "<compartment_name>"
    parent_compartment_ocid: <ocid1.tenancy.oc1..exampleuniqueID>

# Sets the inventory_hostname. Each item is a Jinja2 expression and it gets evaluated on host_vars.
hostname_format_preferences:
  - "display_name+'.oci.com'"
  - "private_ip"
  - "public_ip"

# Excludes a host from the inventory when any of the Jinja2 expression evaluates to true.
exclude_host_filters:
  - "region not in ['iad']"
  - "'<tag_key>' in freeform_tags"
  - "'<tag_value>' == freeform_tags.<tag_key>"
  - "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  - "'<tag_key>' in defined_tags.<namespace>"

# Includes a host in the inventory when any of the Jinja2 expression evaluates to true.
include_host_filters:
  - "display_name is match('.*.oci.com')"
  - "'<tag_key>' in freeform_tags"
  - "'<tag_value>' == freeform_tags.<tag_key>"
  - "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  - "'<tag_key>' in defined_tags.<namespace>"

# Example group results by key
keyed_groups
- key: freeform_tags.<tag key>
  prefix: <my_prefix>
- key: defined_tags.<namespace>.<tag key>
  prefix: <my_prefix>

groups:
  <group_name>: "'<tag_value>' == freeform_tags.<tag_key>"
  <group_name>: "'<tag_value>' == defined_tags.<namespace>.<tag_key>"
  <group_name>: "'<tag_key>' in defined_tags.<namespace>"

# Example to create and modify a host variable
compose:
  ansible_host: display_name+'.oracle.com'

# Example flag to turn on debug mode
debug: true

# Enable Cache
cache: yes
cache_plugin: jsonfile
cache_timeout: 7200
cache_connection: /tmp/oci-cache
cache_prefix: oci_

# DB Hosts
fetch_db_hosts: True

# Compute Hosts (bool type)
fetch_compute_hosts: True

# Process only the primary vnic of a compute instance
primary_vnic_only: True

Solucionando Problemas do Plug-in de Inventário

Se a lista de inventários gerada pelo plug-in de inventário do OCI não incluir todas as instâncias de computação em sua tenancy, revise as informações a seguir.

Permissões do Usuário

Certifique-se de que o usuário tenha as seguintes permissões de política. O OCID do usuário é especificado usando a variável de ambiente OCI_USER ou a seção profile no arquivo de configuração do SDK e da CLI.

Para ver uma lista de permissões de operações da API, consulte Detalhes dos Serviços Básicos.

O plug-in de inventário faz chamadas de API para as seguintes operações:

  • ListCompartments
  • GetCompartment
  • ListVNICAttachments
  • GetVNIC
  • GetSubnet
  • GetVLAN
  • GetVCN
  • ListInstances
  • GetInstance
  • ListDBNodes
  • ListDBSystems
  • ListRegionSubscriptions

Para Obter Mais Informações

Informações detalhadas sobre como usar o plug-in de inventário do OCI estão disponíveis em docs.oracle.com e readthedocs.io.

Você também pode usar o seguinte comando para ver a documentação do plug-in:

ansible-doc -t inventory oracle.oci.oci

Consulte a documentação oficial do Ansible para obter mais informações sobre plug-ins de inventário.