Capítulo 3: OCI Foundations

3.5 Gerenciando o OCI através do OCI CLI

3.5.1 Oracle Cloud Identifier (OCID)

Antes de explorarmos os detalhes do OCI CLI, é importante compreender um elemento essencial ao gerenciar recursos no OCI por meio de código.

O Oracle Cloud Identifier, comumente abreviado como OCID, é um identificador exclusivo atribuído a cada recurso dentro do OCI. Ele é utilizado para identificar de forma única recursos como instâncias de computação, redes virtuais, bancos de dados, volumes de armazenamento, entre outros.

Um OCID utiliza a seguinte sintaxe:

• ocid1

  • Indica a versão do OCID.

• RESOURCE TYPE

  • Identifica o tipo de recurso (como instance, volume, vcn, user, entre outros).

• REALM

  • O termo realm é usado para designar um conjunto de regiões que compartilham entidades.
    • oc1: realm que identifica recursos de uso comercial (usuários individuais, startups ou empresas).
    • oc2: realm que identifica recursos utilizados pelo setor público.
    • oc3: realm que identifica recursos utilizados pelo setor público federal.

• REGION

  • Indica a região do OCI onde o recurso está localizado.

• FUTURE USE

  • Atualmente não utilizado e reservado para uso futuro.

• UNIQUE ID

  • String alfanumérica gerada de forma exclusiva para criar a identificação única do recurso.

Por exemplo, o OCID que identifica de forma única um Compute Instance tem o seguinte formato:

Alguns OCIDs que identificam recursos globais omitem a parte que indica a região. Por exemplo, os OCIDs utilizados para identificar usuários, grupos, políticas, compartimentos e tenancy, não incluem a região:

Além de sua função de identificação, os OCIDs são utilizados para atender a dependências ao criar um recurso. Por exemplo, para criar um Internet Gateway por meio do OCI CLI, é necessário fornecer tanto o OCID do compartimento (--compartment-id) quanto o OCID da VCN (--vcn-id):

3.5.2 Instalação do OCI CLI

Para começar a utilizar o OCI CLI, é necessário primeiro instalá-lo de acordo com o seu sistema operacional. No meu caso, o OCI CLI será instalado em um Oracle Linux versão 8.

1
2

$ cat /etc/oracle-release
Oracle Linux Server release 8.10

1. Baixar o instalador do OCI CLI através do seguinte comando:

1

$ wget https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh

2. Execute o script que foi baixado com a opção "--accept-all-defaults" para realizar uma instalação em que todas as perguntas serão respondidas com os valores padrão:

1

$ sh ./install.sh --accept-all-defaults

3. Por fim, para verificar se o OCI CLI foi instalado com sucesso, basta executar o comando abaixo para exibir a sua versão:

1
2

$ oci -v
3.52.1

Atualizando o OCI CLI

É sempre recomendável verificar se estamos utilizando a versão mais recente do OCI CLI disponível.

1
2
3

$ oci --latest-version
3.53.0
You are using OCI CLI version 3.52.1, however version 3.53.0 is available. You should consider upgrading using https://docs.oracle.com/iaas/Content/API/SDKDocs/cliupgrading.htm

Neste caso, o comando nos alertou sobre a necessidade de atualização. Além de corrigir bugs e implementar melhorias, a atualização também permite a interação com novos serviços do OCI.

Para realizar a atualização, basta executar o comando abaixo:

1

$ pip3 install oci-cli --upgrade

Pronto! Agora podemos confirmar que a atualização do OCI CLI foi bem-sucedida, pois não há mais avisos relacionados à atualização de versão:

1
2

$ oci --latest-version
3.53.0

3.5.3 APIs do OCI

O OCI como todo provedor de computação em Nuvem, disponibilizam seus serviços através de um conjunto de diferentes APIs.

As APIs do OCI são públicas, acessíveis pela Internet por meio do protocolo HTTPS. Por exemplo, o conjunto de APIs denominado Core Services API, permite gerenciar recursos como VCN, Compute Instances e Block Storage.

Todo serviço no OCI, disponível por meio de uma API, possui um endpoint exclusivo, que varia conforme a região. Para o Core Services API, o endpoint correspondente é:

O fato de as APIs serem públicas, ou seja, possuírem um endpoint acessível pela Internet, não significa que qualquer pessoa possa criar ou excluir recursos. Por exemplo, ao tentar criar uma VCN sem uma credencial válida, a resposta obtida será "NotAuthenticated", conforme abaixo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

$ curl -X POST https://iaas.sa-saopaulo-1.oraclecloud.com/20160918/vcns \
> -H "Content-Type: application/json" \
> -d '{
>   "compartmentId": "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc",
>   "displayName": "vcn-saopaulo",
>   "cidrBlock": "172.16.0.0/16"
> }'
{
  "code" : "NotAuthenticated",
  "message" : "The required information to complete authentication was not provided or was incorrect."
}

Para interagir com o OCI e criar recursos, é necessário ter um usuário que possa ser autenticado e autorizado com sucesso. Como inicialmente utilizaremos o OCI CLI e o Terraform para criar recursos de infraestrutura, ambos requerem uma API Key válida, que deve ser criada previamente.

Iniciaremos pelo processo de autenticação, que envolve o uso de API Key.

API Keys

Uma API Key é um conjunto de chaves criptográficas que servem tanto para o processo de autenticação quanto para assinar as requisições enviadas as APIs do OCI.

Sem uma API Key, que deve ser associada a um usuário válido, não é possível estabelecer comunicação com as APIs do OCI, seja por meio do OCI CLI, Terraform ou SDK.

É possível criar uma API Key manualmente utilizando o utilitário OpenSSL, mas a criação é mais simples e prática por meio da Web Console.

Para criar uma API Key para um usuário específico por meio da Web Console, siga o passo a passo abaixo:

1. Acessar o perfil do usuário no canto superior direito da Web Console:

2. Dentro do perfil do usuário, no canto inferior esquerdo, selecione API keys e, em seguida, clique no botão Add API key:

3. Na tela Add API key, selecione Generate API key pair e, em seguida, faça o download e salve em um local seguro tanto a Private Key quanto a Public Key:

4. Clique no botão Add para concluir a adição da API Key:

5. Por fim, o OCI exibe um conjunto de informações que devem ser inseridas no arquivo "~/.oci/config" para serem utilizadas pelo OCI CLI:

Utilizando a API Key com o OCI CLI

1. Crie o diretório "~/.oci" e depois o arquivo config" dentro dele:

1
2
3

$ mkdir .oci
$ touch .oci/config
$ chmod 0400 .oci/config

2. Insira o conjunto de informações fornecidas anteriormente (API Keys - item 5) no arquivo "~/.oci/config". O conteúdo deste arquivo deve ser semelhante a isto:

1
2
3
4
5
6
7

$ cat ~/.oci/config
[DEFAULT]
key_file=/home/darmbrust/.oci/api.key
user=ocid1.user.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
fingerprint=4f:f7:42:44:f6:c1:bc:2b:da:dd:fd:d5:43:28:e1:9a
tenancy=ocid1.tenancy.oc1..aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
region=sa-saopaulo-1

3. Dentro do diretório "~/.oci", crie o arquivo "api.key":

1
2

$ touch .oci/api.key
$ chmod 0400 .oci/api.key

4. Transfira o conteúdo da chave privada que foi baixada anteriormente (API Keys - item 3) para o arquivo "~/.oci/api.key". O conteúdo deste arquivo deve ser semelhante a isto:

1
2
3
4
5
6

$ cat ~/.oci/api.key
-----BEGIN PRIVATE KEY-----
MIIMIIMRGDkRGDkRGDkRGDkRGDkRGDkMIIMIIMIIMIRGDkMIIMIIMIIMIRGDk
RGDkRGDkRGDkRGDkRGDkMIIMIIMIIMIRGDkMIIMIIMIIMIRGDk
-----END PRIVATE KEY-----
OCI_API_KEY

5. Teste a comunicação do OCI CLI ao OCI através de um simples comando:

1
2
3
4

$ oci os ns get
{
  "data": "WYYdXX82dnaS"
}

3.5.4 Trabalhando com o OCI CLI

Após o OCI CLI estar devidamente instalado e funcionando com as configurações do seu Tenancy, é hora de entender em como trabalhar diretamente com o OCI através do OCI CLI.

Criar e gerenciar sua infraestrutura no OCI utilizando OCI CLI ou Terraform é mais rápido do que realizar operações manualmente através de cliques na Web Console. Além disso, ao trabalhar com código, você pode automatizar tarefas repetitivas, versionar suas configurações para acompanhar alterações, reverter para versões anteriores quando necessário e facilitar a colaboração com outros membros da equipe.

Para demonstrar a utilização do OCI CLI, apresentarei a criação de uma VCN (Virtual Cloud Network) por meio de uma sequência de etapas.

1. O primeiro passo é localizar o recurso desejado no link Oracle Cloud Infrastructure CLI Command Reference. Os recursos disponíveis de redes no OCI, incluindo a VCN, estes estão contidos em Networking Service (network):

2. Dentro de Networking Service (network), você encontrará diversos comandos relacionados aos diferentes recursos de rede disponíveis no OCI. Para o nosso exemplo, iremos utilizar a vcn:

3. Cada recurso no OCI que pode ser gerenciado pelo OCI CLI possui um conjunto específico de comandos ou ações que podem ser invocadas, permitindo a criação, modificação ou alteração desse recurso. Para a vcn, utilizaremos a ação create:

4. Dentro do comando ou ação, além da descrição e do exemplo de uso, você encontrará os Parâmetros Obrigatórios (Required Parameters), os Parâmetros Opcionais (Optional Parameters) e os Parâmetros Globais (Global Parameters), que determinam as propriedades do recurso a ser criado ou modificado:

Parâmetros Globais

Os parâmetros globais como o própio nome diz, são globais pois podem ser usados juntos com qualquer outro comando do OCI CLI.

Para os exemplos apresentados no livro, os parâmetros globais mais utilizados são:

• --region

Permite especificar a região do OCI onde ocorrerá a interação com um determinado recurso.

• --query

Parâmetro utilizado para filtrar a resposta JSON recebida do OCI CLI. A filtragem é especialmente útil ao lidar com grandes volumes de informações vindas através do OCI CLI.

Esta opção utiliza a linguagem de consulta JMESPath para manipulação de JSON.

Por exemplo, o comando abaixo utiliza a opção --query para listar as VCNs cujo nome contém "vcn-saopaulo":

1
2
3
4

$ oci network vcn list \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --all \
> --query "data [?contains(\"display-name\",'vcn-saopaulo')]"

Parâmetros Simples e Complexos

Tanto um parâmetro sendo obrigatório ou opcional, pode aceitar um valor simples ou complexo. O valor simples é um único valor, que pode ser um texto, um número ou um valor booleano. Por outro lado, o valor complexo deve ser fornecido no formato JSON, que pode combinar diferentes tipos de valores, como texto, número e booleano.

É possível utilizar o parâmetro global --generate-param-json-input para gerar a estrutura do valor JSON que um determinado parâmetro complexo espera receber. Por exemplo, o parâmetro --cidr-blocks espera receber uma lista de valores do tipo string (array de strings) quando especificado:

1
2
3
4
5

$ oci network vcn create --generate-param-json-input cidr-blocks
[
  "string",
  "string"
]

Ciclo de Vida (Lifecycle)

Muitos recursos do OCI possuem o chamado "Ciclo de Vida" (Lifecycle), que indica o estado atual de um determinado recurso. É por meio desse "ciclo de vida" que é possível determinar se um recurso já está disponível para uso ou se ainda está em processo de criação, atualização ou exclusão.

Por exemplo, quando um recurso é solicitado para criação, ele não é criado imediatamente. Após o OCI receber a instrução de criação, essa solicitação é colocada em uma fila de processamento. Se tudo ocorrer conforme o esperado, o recurso é então criado e disponibilizado para uso. Esse processo não se aplica apenas à ação de "criar", ações de "exclusão" ou "atualização" também são submetidas a uma fila de processamento.

É importante destacar que, durante as etapas do "ciclo de vida", diversas outras atividades são realizadas, como a verificação das permissões do usuário que está solicitando a criação e a confirmação da disponibilidade de recursos computacionais.

Você verá que é importante saber lidar com essas operações assíncronas que ocorrem durante o "ciclo de vida" de um recurso, em scripts que utilizam o OCI CLI para criar outros recursos. Por exemplo, não é possível criar um Compute Instances sem que uma sub-rede e uma VCN estejam no estado AVAILABLE.

O parâmetro --wait-for-state, disponível na maioria dos recursos, pode ser usado para aguardar a conclusão de uma determinada etapada do "ciclo de vida" antes de liberar o shell para execução de um próximo comando.

O significado de cada etapa do "ciclo de vida" da vcn é descrito a seguir:

• AVAILABLE

  • A VCN está pronta e disponível para ser utilizada.

• PROVISIONING

  • Esse estado indica que o comando para criar a VCN foi aceito pelo OCI, e o recurso agora está na fila de criação ou provisionamento.

• UPDATING

  • A VCN encontra-se em em processo de atualização.

• TERMINATING

  • Esse estado indica que a VCN entrou em processo de exclusão ou terminate.

• TERMINATED

  • A VCN foi excluída com sucesso e não existe mais.

Exemplo: Criando e Consultando Informações sobre uma VCN

O comando a seguir pode ser utilizado para criar uma VCN:

1
2
3
4
5
6

$ oci network vcn create \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --cidr-blocks "['10.100.0.0/16', '192.168.0.0/24']" \
> --display-name "vcn-saopaulo" \
> --wait-for-state "AVAILABLE"

Observe que, após a execução do comando, é exibida a seguinte mensagem:

Isso significa que o comando aguardará até que a VCN atinja o estado AVAILABLE antes de liberar o shell novamente.

Após a conclusão bem-sucedida da execução, uma resposta do OCI em formato JSON será retornada que incluem algumas informações referente a VCN que acaba de ser criada:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

{
  "data": {
    "byoipv6-cidr-blocks": null,
    "cidr-block": "10.100.0.0/16",
    "cidr-blocks": [
      "10.100.0.0/16",
      "192.168.0.0/24"
    ],
    "compartment-id": "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc",
    "default-dhcp-options-id": "ocid1.dhcpoptions.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc",
    "default-route-table-id": "ocid1.routetable.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc",
    "default-security-list-id": "ocid1.securitylist.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/darmbrust@gmail.com",
        "CreatedOn": "2025-03-24T18:34:10.160Z"
      }
    },
    "display-name": "vcn-saopaulo",
    "dns-label": null,
    "freeform-tags": {},
    "id": "ocid1.vcn.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc",
    "ipv6-cidr-blocks": null,
    "ipv6-private-cidr-blocks": null,
    "lifecycle-state": "AVAILABLE",
    "security-attributes": {},
    "time-created": "2025-03-24T18:34:10.244000+00:00",
    "vcn-domain-name": null
  },
  "etag": "4aba8b9d"
}

O OCID da VCN recém-criada está disponível na chave id. Com esse identificador, você pode consultar os detalhes relacionados à VCN:

1
2

$ oci network vcn get \
> --vcn-id "ocid1.vcn.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc"

Outra maneira de obter o OCID dos recursos é através do comando "list". No exemplo abaixo, serão retornados todos os OCIDs das VCNs que estão criadas no compartimento especificado:

1
2
3

$ oci network vcn list \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --all

3.5.5 Work Request

Vimos que a maioria dos recursos possuem um "ciclo de vida", que indica diferentes etapas pelas quais o recurso passa antes de concluir uma ação solicitada pelo usuário.

As ações que não produzem resultados imediatos geram o que é conhecido como Work Request, que é um OCID utilizado para consultar informações relacionadas a uma etapa específica do "ciclo de vida". Isso ocorre porque solicitações que não têm resultados imediatos são assíncronas e podem levar um tempo indeterminado para serem concluídas com sucesso.

Por exemplo, ao criar o componente de rede DRG, o resultado da operação inclui o campo opc-work-request-id, que indica o OCID do Work Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

$ oci network drg create \
> --region "sa-saopaulo-1" \
> --compartment-id "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc" \
> --display-name "drg"
{
  "data": {
    "compartment-id": "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc",
    "default-drg-route-tables": {
      "ipsec-tunnel": null,
      "remote-peering-connection": null,
      "vcn": null,
      "virtual-circuit": null
    },
    "default-export-drg-route-distribution-id": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/darmbrust@gmail.com",
        "CreatedOn": "2025-03-24T19:27:04.790Z"
      }
    },
    "display-name": "drg",
    "freeform-tags": {},
    "id": "ocid1.drg.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc",
    "lifecycle-state": "PROVISIONING",
    "time-created": "2025-03-24T19:27:04.818000+00:00"
  },
  "etag": "282241271",
  "opc-work-request-id": "ocid1.coreservicesworkrequest.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc"
}

Para consultar informações sobre o Work Request, utilize o valor do opc-work-request-id com o comando abaixo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

$ oci work-requests work-request get \
> --region "sa-saopaulo-1" \
> --work-request-id "ocid1.coreservicesworkrequest.oc1.sa-sa
opaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc"
{
  "data": {
    "compartment-id": "ocid1.compartment.oc1..aaaaaaaaaaaaaaaabbbbbbbbccc",
    "id": "ocid1.coreservicesworkrequest.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc",
    "operation-type": "create",
    "percent-complete": 0.0,
    "resources": [
      {
        "action-type": "CREATED",
        "entity-type": "drg",
        "entity-uri": "/20160918/drgs/ocid1.drg.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc",
        "identifier": "ocid1.drg.oc1.sa-saopaulo-1.aaaaaaaaaaaaaaaabbbbbbbbccc"
      }
    ],
    "status": "SUCCEEDED",
    "time-accepted": "2025-03-24T19:27:04.899000+00:00",
    "time-finished": "2025-03-24T19:27:09.988000+00:00",
    "time-started": null
  }
}

Trabalhar com Work Request pode ser extremamente útil em diversos cenários. Por exemplo, considere a situação em que você precisa disponibilizar uma aplicação web por meio de um Load Balancer. No entanto, antes, é necessário que o processo de provisionamento de um Compute Instance, que irá hospedar a aplicação, seja concluído.

3.5.6 Cloud Shell

Uma instalação "pronta para uso" do OCI CLI, está disponível por meio do Cloud Shell, que pode ser acessado pela Web Console:

O Cloud Shell é um terminal Linux acessível por meio da Web Console que oferece um shell pré-autenticado com diversas ferramentas já instaladas, incluindo o OCI CLI. Isso significa que não é necessário realizar a instalação e configuração de uma API Key.