Diretrizes para Pilhas

Diretrizes Obrigatórias

Veja a seguir as diretrizes obrigatórias para pilhas listadas no Oracle Cloud Infrastructure Marketplace. Cada diretriz deve ser seguida. Antes de ser publicado, cada artefato de pilha é validado em relação a cada uma dessas diretrizes.

1. O artefato de pilha deve ser um arquivo zip, incluindo o(s) arquivo(s) de configuração do Terraform e um arquivo de Esquema.
   • O zip deve incluir pelo menos um arquivo de configuração (.tf) na pasta raiz.
   • O zip deve incluir o arquivo de Esquema (.yaml) na pasta raiz.
   • O zip não deve incluir um arquivo de estado do Terraform no arquivo zip. Os arquivos de estado são gerenciados pelo Oracle Resource Manager (ORM). Quando os clientes iniciam uma pilha, o ORM cria e gerencia os recursos e o arquivo de estado fica disponível apenas para download.
   • O zip não deve incluir a pasta de configuração de runtime do Terraform (.terraform).
2. A configuração do Terraform só deve usar imagens de instância Aprovadas ou Publicadas (Públicas ou Privadas) do Marketplace. Ele deve ter uma assinatura do Marketplace para cada uma dessas imagens. Ele deve ter referências codificadas para estas Imagens do Marketplace. Consulte Amostra de Configuração do Terraform para Uso e Assinatura de Imagem do Marketplace para obter mais detalhes.
3. Os binários não devem ser baixados de repositórios externos. Todos os binários e dependências devem ser incorporados na Imagem do Marketplace publicada.
4. O provisionador de execução remota do Terraform só deve ser executado no domínio do Oracle Cloud Infrastructure. Ele não deve baixar arquivos em um servidor remoto.
5. O download de código ou binários de terceiros não deve ser feito usando cloud-init.
   1. cloud-init é um utilitário de configuração de inicialização comumente usado para instâncias de computação em nuvem. Ele aceita a configuração por meio de mecanismos de dados do usuário especificados como parte da definição de metadados no recurso oci_core_instance.
   2. Há vários formatos de dados do usuário suportados por cloud-init. Consulte https://cloudinit.readthedocs.io/en/latest/topics/format.html.
   3. Independentemente do formato de dados do usuário, cloud-init NÃO DEVE ser usado para baixar qualquer código de terceiros ou binário. Todos os binários necessários durante o processo de inicialização da instância (bootstrap), se não estiverem disponíveis na imagem, deverão ser baixados por um processo (script) criado como parte da distribuição da imagem, não injetado via cloud-init (por exemplo, aproveitando wget).
   4. No entanto, você pode ter um modelo cloud-init configurado para que os clientes usem em alguns cenários específicos, por exemplo, para importar um arquivo de chave de licença ou para importar um arquivo de configuração. Nesse caso, você deve fornecer uma variável no código do modelo do Terraform para permitir que os clientes insiram alguns dados no bloco de construção cloud-init, por exemplo, aproveitando a origem de dados template_file do Terraform.
6. O provedor Terraform deve ser o Oracle Cloud Infrastructure. Outros provedores de nuvem ou provedores de aplicativos de terceiros não são suportados.
7. Se um módulo Terraform for usado, ele deverá ser carregado de caminhos relativos locais. Não é possível carregá-lo a partir de um repositório remoto.
8. A configuração do Terraform deve usar a autenticação do controlador de instâncias.

9. Especifique as versões mínima e máxima do Terraform suportadas nas quais você testou sua pilha.

   • Especifique a versão mínima necessária do Terraform no formato: ~> <major_version>.<minor_version>.<patch_version>.

     Onde, o patch_version é sempre definido como 0. Quando uma pilha é iniciada, o Resource Manager verifica o <major_version>.<minor_version> que você definiu em seu código e usa a versão de patch mais recente disponível. É por isso que você deve usar o sinal ~> em vez do sinal => ao especificar a versão mínima necessária do Terraform.

     Por exemplo, ~> 0.14.0 indica que as versões suportadas do Terraform são 0.14.0 ou posteriores.

   • Especifique a versão máxima necessária do Terraform no formato: < <major_version>.<minor_version>.

     Por exemplo, < 0.15 indica que as versões do Terraform suportadas são anteriores a 0.15.

   O exemplo a seguir mostra como especificar as versões mínima e máxima do Terraform suportadas quando você testou sua pilha apenas no Terraform 0.14.

   terraform 
   { required_version = "~> 0.14.0, < 0.15" }

Para obter mais informações sobre o Terraform, incluindo o provedor Oracle Cloud Infrastructure, a autenticação do controlador de instâncias e o provisionador de execução remota, consulte a documentação do Terraform para Configuração do Provedor. Para obter informações sobre as versões suportadas do Terraform, consulte Conceitos Básicos do Provedor Terraform na Documentação do Oracle Cloud Infrastructure.

Diretrizes de Codificação para Configurações do Terraform

As diretrizes a seguir são recomendadas para pilhas listadas no Oracle Cloud Infrastructure Marketplace. Cada diretriz é considerada uma prática recomendada que deve ser seguida, se possível.

• O artefato de pilha deve permitir que os clientes criem todos os recursos de infraestrutura ou aponte para os existentes (rede, armazenamento etc.).
• As convenções de nomenclatura e a formatação devem ser seguidas:
  • Invólucro - Use lower_snake_case para todos os nomes. Isso se aplica a nomes de variáveis, nomes de recursos, nomes de módulos, nomes de arquivos, nomes de exibição etc.
  • Especificando o Tipo de Recurso - Não inclua o recurso ou o tipo de origem de dados no nome. No Terraform, os recursos e as origens de dados são sempre referenciados por <type>.<name>. Como tal, não há necessidade de incluir o tipo no próprio nome.
  • ID vs OCID - No Oracle Cloud Infrastructure, id geralmente se refere a um campo que recebe um OCID. Dessa forma, as variáveis devem usar id ao fazer referência a valores de OCID, em vez de usar ocid.
  • Nomes de Variáveis - Os nomes de variáveis para recursos do Oracle Cloud Infrastructure geralmente devem usar o mesmo nome usado para o recurso Terraform.
  • Nomes para Exibição - Os nomes para exibição dos recursos do Oracle Cloud Infrastructure geralmente devem usar o mesmo nome usado para o recurso Terraform.
  • Variáveis e saídas do módulo de nomeação - Ao usar um módulo, a nomeação da entrada (variáveis) e as saídas devem ser expostas ao chamador.
  • terraform fmt deve ser aplicado a todo o Terraform antes de fazer check-in.