Documentação do Oracle Cloud Infrastructure

Especificação de Comando

A especificação de comando contém comandos de shell e configurações que são executados durante uma implantação. A especificação de comando é gravada em YAML. O conteúdo do arquivo pode ser especificado conforme inserido ou a especificação pode ser armazenada em um repositório do serviço Artifact Registry.

Para executar qualquer arquivo binário que não seja pré-instalado pela Oracle, faça download dele diretamente para a pasta raiz ou faça download para a pasta do espaço de trabalho e mova-o para a pasta raiz antes de executar.

A especificação de comando está organizada nas seguintes seções:

  • Configuração das variáveis de ambiente.
  • Artefatos de entrada.
  • Etapas a serem executadas em sequência.

Sintaxe de Especificação de Comando

version: 0.1
component: command
timeoutInSeconds: 10000
shell: bash
failImmediatelyOnError: true
env:
  variables:
    key: "value"
    key: "value"
  vaultVariables:
    key: "secret-id"
 
inputArtifacts:
  - name: artifact-name
    type: GENERIC_ARTIFACT
    artifactId: "artifact-ocid"
    registryId: OCID of the Artifact Registry
    path: path of the artifact in the Registry
    version: version of the artifact
    location: target-location
  - name: artifact-name
    type: URL
    url: downloadable link
    location: target-location
 
steps:
  - type: Command
    name: step-name
    shell: shellType
    timeoutInSeconds: 650
    failImmediatelyOnError: true
    command: command
    onFailure:
      - type: Command
        command: |
          command
          command
        timeoutInSeconds: 400
 
  - type: Command
    name: step-name
    command: |
      command
      command
      command
    onFailure:
      - type: Command
        command: |
          command
        timeoutInSeconds: 400

Parâmetros de Especificação de Comando

A seguir estão os parâmetros de especificação de comando e os seus detalhes:

Parâmetro Descrição
version Obrigatório. Indica a versão da especificação de comando. Uma versão ausente ou inválida causa falha no estágio do Shell.

O valor suportado é 0.1.
component Obrigatório. Indica um componente específico no DevOps. Um valor ausente ou inválido causa falha no estágio.

O valor suportado é command.
timeoutInSeconds Opcional. Especifica o timeout para todo o arquivo de especificação de comando. Cada 'etapa' também pode ter seu próprio valor de timeout.

Se um valor não for especificado, o valor padrão de 8 horas será usado. O valor máximo permitido é 8 horas.
shell Opcional. Especifica o shell a ser usado no nível global da especificação de comando. O valor pode ser substituído no nível da 'etapa'.

Os valores permitidos são /bin/sh e bash. Se não for especificado, o valor padrão bash será usado.
failImmediatelyOnError Opcional. Especifica se a implantação deve continuar caso ocorra falha de qualquer comando na etapa com um valor de saída diferente de zero. Se não for especificado, o valor padrão será false e a etapa continuará. Os valores permitidos são true e false. O OCI recomenda definir o valor desse atributo como true.
env

Opcional. Você pode definir variáveis personalizadas. Há suporte para três tipos de variáveis:

  • env/variáveis: Opcional. A chave deve ser compatível com variáveis de ambiente de string e POSIX. O valor pode ser qualquer string. O escopo dessa variável é a execução do arquivo de especificação de comando. Qualquer alteração no valor da variável estará visível nas etapas subsequentes. Essas variáveis estão disponíveis como variáveis de ambiente para todas as etapas do arquivo de especificação de comando.

    Se o valor da variável tiver um caractere de nova linha (\n) ou de retorno de transporte (\r), ele será substituído por espaço nas etapas subsequentes.

  • env/vaultVariables: Opcional. A chave deve ser compatível com variáveis de ambiente de string e POSIX. O valor deve ser um OCID do segredo do vault. O vault e o pipeline devem ser da mesma tenancy. A tenancy deve ter uma política apropriada para permitir que recursos do pipeline de implantação acessem o segredo.

    O escopo dessa variável é a execução do arquivo de especificação de comando e está disponível para todas as etapas do arquivo. O valor dessas variáveis é recuperado do vault e disponibilizado como variáveis de ambiente para todas as etapas do arquivo de especificação de comando.

  • env/exportedVariables: Opcional. Uma lista de variáveis pode ser declarada aqui. O nome da variável deve ser compatível com uma variável de ambiente de string e POSIX. O valor pode ser designado em qualquer etapa dentro do arquivo de especificação de comando. O escopo dessa variável é o pipeline de implantação. Qualquer variável exportada só está disponível nos estágios do Shell do mesmo pipeline.
inputArtifacts

Opcional. Usado para definir uma lista de artefatos de entrada que são necessários para executar o estágio atual do Shell.

Suporta artefatos genéricos do serviço Artifact Registry.

Os parâmetros são os seguintes:

  • inputArtifacts/*/url: Opcional. O URL HTTP externo para download do artefato de entrada deve ser informado. O URL deve estar disponível publicamente. No momento, não há suporte para a autenticação/autorização.
  • inputArtifacts/*/name: Obrigatório. Este nome é usado para fazer referência aos artefatos na execução do comando.
  • inputArtifacts/*/location: obrigatório. Um caminho de destino do sistema de arquivos local no qual o artefato de entrada precisa ser baixado. O caminho pode ser especificado em um destes métodos:
    • ${OCI_PRIMARY_SOURCE_DIR}/pom.xml
    • ${OCI_WORKSPACE_DIR}/[source-name]/pom.xml
    • /workspace/[source-name]/pom.xml
    • Caminho relativo do home do projeto, pom.xml

    Com qualquer um dos valores, é feito download do artefato de entrada para o diretório home de origem principal com um nome de arquivo, pom.xml.

    O local não suporta exportedVariables ou variáveis de pipeline.

  • inputArtifacts/*/type: Obrigatório. O tipo do artefato de entrada que precisa ser submetido a download. Os valores permitidos são URL e GENERIC_ARTIFACT.
  • inputArtifacts/*/artifactld: Obrigatório. O OCID do artefato. Se você tiver fornecido o OCID, o pipeline de implantação ignorará o registryId, o caminho e a versão.
  • inputArtifacts/*/registryld: Obrigatório. O OCID do Artifact Registry.
  • inputArtifacts/*/path: Obrigatório. O caminho de destino do artefato.
  • inputArtifacts/*/version: Obrigatório. A versão do artefato.

Observação: Para o tipo GENERIC_ARTIFACT de artefato de entrada, você pode fornecer como um parâmetro obrigatório o OCID do artefato ou uma combinação de ID do registro, caminho e versão do artefato.
steps

Obrigatório. Esta seção define uma lista de etapas que precisam ser executadas.

  • steps*/type: Obrigatório. Especifica o tipo da etapa. Suporta os seguintes valores: Command
  • steps/*/name: Opcional. Um nome amigável para a etapa.

Tipos de Etapa

Comando

Nome do atributo Descrição
command Há suporte para comandos de linha única e de várias linhas. Todos os comandos especificados em uma etapa são executados na mesma sessão de shell. Com base no valor steps/*/shell, os comandos podem ser shell ou bash.

Fail-fast não ativado. Para que a etapa seja bem-sucedida, a saída do último comando em uma etapa é considerada. Se o último código de saída do comando for 0, a etapa será considerada como bem-sucedida.
timeoutInSeconds (Opcional) Especifica o timeout da etapa. Se não for informado, o valor será herdado do parâmetro timeoutInSeconds global. O valor máximo permitido é 8 horas.
shell (Opcional) Especifica o tipo de shell da etapa atual. Se não for especificado, o valor será herdado do parâmetro shell global. Os valores permitidos são /bin/sh e shell.
onFailure (Opcional) Uma lista de etapas que devem ser executadas sem a saída normal do estágio do Shell. Execute se a etapa correspondente falhar e, após a execução, a especificação de comando for encerrada.

O tratamento da falha não afeta o status do estágio do Shell. Se qualquer uma das etapas falhar, o status do estágio do Shell permanecerá failed, embora seja tratado usando o bloco onFailure.
failImmediatelyOnError (Opcional) Especifica se a implantação deve continuar caso ocorra falha de qualquer comando na etapa com um valor de saída diferente de zero. Se não for especificado, o valor padrão será false e a etapa continuará. Os valores permitidos são true e false. O OCI recomenda definir o valor desse atributo como true.

O valor do atributo failImmediatelyOnError definido em steps tem precedência sobre o mesmo valor de atributo definido fora de steps.

Variáveis Predefinidas do Sistema

O serviço DevOps fornece um conjunto de variáveis de sistema predefinidas com valores padrão que você pode usar na especificação de comando.

Variável Descrição
OCI_DEPLOYMENT_ID O OCID da implantação atual.
OCI_PIPELINE_ID O OCID do pipeline de implantação atual.
OCI_RESOURCE_PRINCIPAL_RPST Token do controlador de recursos.
OCI_RESOURCE_PRINCIPAL_VERSION Versão do controlador de recursos.
OCI_CLI_AUTH O OCI CLI AUTH pré-configurado para usar o controlador de recursos.
OCI_RESOURCE_PRINCIPAL_REGION Região do controlador de recursos.
OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM Caminho da chave privada do controlador de recursos.

Exemplo de Especificação de Comando

Exemplo: Crie um namespace do OKE.

version: 0.1
component: command
timeoutInSeconds: 6000
shell: bash

steps:
  - type: Command
    timeoutInSeconds: 600
    name: "Setup kube config and get nodes"
    command: |
      oci ce cluster create-kubeconfig --cluster-id ${clusterid} --file $HOME/.kube/config --region us-ashburn-1 --token-version 2.0.0  --kube-endpoint ${endpoint}
      kubectl get nodes
    onFailure:
      - type: Command
        command: |
          echo "Failed to set up kube config and get nodes"
        timeoutInSeconds: 60