Deploy de Aplicação e Infraestrutura

Nesta seção, você encontra um passo a passo para configurar o StackSpot Self-Hosted Workflow para realizar deploys de Aplicações ou Infraestruturas em pipelines do seu provedor Cloud. O conteúdo é voltado para pessoas desenvolvedoras, SREs e administradores com experiência em serviços de Cloud e pipelines CI/CD.

Como configurar os deployments de Self-Hosted usando o StackSpot Workflow

O deploy de Aplicações com o Workflow da StackSpot é agnóstico aos serviços de Cloud, você pode integrar qualquer provedor Cloud que desejar desde que a StackSpot forneça o suporte e você tenha os requisitos necessários de cada provedor.

Você pode usar os seguintes provedores de Cloud:

Amazon Web Services (AWS)
Azure DevOps

O deploy é orquestrado pelo Workflow stackspot-core/stackspot-deploy@5 do tipo reusable, ou seja, você deve usá-lo dentro do seu Workflow que fará o deploy. Este Workflow possui todos os inputs e configurações para a integração com os provedores Cloud.

Informação Adicional

Usar o StackSpot Workflow stackspot-core/stackspot-deploy@5 para orquestrar os seus deploys, permite que você faça deploys com provedores diferentes. Por exemplo, um único Workflow pode executar o deploy com qualquer provedor Cloud como AWS e/ou Azure DevOps em uma mesma Infraestrutura na Cloud.

Pré-requisitos

Permissão de escrita em um repositório do seu provedor Cloud e acesso à criação/edição de pipelines.
Conta do serviço Cloud com permissões para criar recursos.
Credencial de Serviço StackSpot (Client ID e Client Key).
Infraestrutura (Storages) do seu provedor Cloud configurados para armazenar estados do Terraform e artefatos de IaC.
Aplicação ou Infraestrutura criadas e registradas na StackSpot.

Como criar um StackSpot Workflow para Deploy

Passo 1. Crie o Workflow para o deploy

Para o deploy da sua Aplicação ou Infraestrutura, crie um Workflow do tipo deploy para obter os inputs para o Workflow que orquestra o deploy com o StackSpot Self-Hosted.

Crie o Workflow com o comando a seguir:

stk create workflow

Exemplo do StackSpot Workflow para executar um deploy de Aplicação/Infraestrutura 'workflow.yaml'
schema-version: v1
kind: workflow
metadata:
  name: deployworkflow
  display-name: deployworkflow
  description: Example of a deploy workflow
  version: 0.0.1
spec:
  type: deploy
  label: Deploy Workflow Example
  targets:
  - infra
  docs:
    en-us: docs/en_us/docs.md
    pt-br: docs/pt_br/docs.md

O deploy pode ser executado quando quiser. Antes de iniciar o deploy você pode configurar o seu Workflow para executar Actions e outro Workflows. Por exemplo, você pode adicionar uma Action para recuperar as credenciais do seu provedor Cloud, ou um Workflow que faz a instalação da STK CLI em sua pipeline.

Passo 2. Adicione os inputs do seu provedor no Workflow de deploy

O exemplo a seguir vai capturar os inputs necessários para os serviços AWS e Azure DevOps:

AWS
Azure DevOps

Dica!

Autentique-se usando as variáveis de ambiente stk_client_id, stk_client_key da sua Organização StackSpot.

Trecho de código dos inputs do Workflow
inputs:
  - label: Stackspot Credential Client ID
    name: stk_client_id
    type: password
    required: True
  - label: Stackspot Credential Client Key
    name: stk_client_key
    type: password
    required: True
  - label: AWS Credential accessKey
    name: accessKey
    type: password
    required: True
  - label: AWS Credential secretKey
    name: secretKey
    type: password
    required: True
  - label: AWS Credential accessToken
    name: accessToken
    subscriptionId: password
    required: True
  - label: Application Repo name
    name: repository_name
    subscriptionId: text
    required: True

Dica!

Autentique-se usando as variáveis de ambiente stk_client_id, stk_client_key da sua Organização StackSpot.

Trecho de código dos inputs do Workflow
inputs:
  - label: Stackspot Credential Client ID
    name: stk_client_id
    type: password
    required: True
  - label: Stackspot Credential Client Key
    name: stk_client_key
    type: password
    required: True
  - label: Azure Credential clientId
    name: clientId
    type: password
    required: True
  - label: Azure Credential clientSecret
    name: clientSecret
    type: password
    required: True
  - label: Azure Credential tenantId
    name: tenantId
    type: password
    required: True
  - label: Azure Credential subscriptionId
    name: subscriptionId
    type: password
    required: True
  - label: Application Repo name
    name: repository_name
    type: text
    required: True

Passo 3. Crie o Job e Step para executar o deploy

Crie um Job para o deploy e adicione o Step que vai executar Workflow para orquestrar o deploy;

Atenção!

O Step for do tipo workflow deve ser único dentro do Job.

Declare as variáveis dos inputs do seu Workflow nos inputs do Step com as expressões a seguir:

authenticate_client_id: "{{ inputs.stk_client_id }}"
authenticate_client_key: "{{ inputs.stk_client_key }}"
repository_name: "{{ inputs.repository_name }}"

Preencha as variáveis a seguir com um JSON válido e use o contrato de cada provedor com as expressões a seguir:

cloud_credentials: serão utilizadas pelo Terraform para criar, atualizar e remover sua infraestrutura na AWS e/ou Azure.

Dica!

Você pode fornecer uma lista de credenciais, permitindo realizar o deploy em contas AWS e Azure simultaneamente na mesma infraestrutura StackSpot.

Exemplo:

cloud_credentials preenchida com uma lista de provedores AWS e Azure DevOps
cloud_credentials: |
          [
            {
              "type": "AZ_PRINC_SECRET",
              "azPrincSecret": {
                "clientId": "{{ inputs.clientId }}",
                "clientSecret": "{{ inputs.clientSecret }}",
                "tenantId": "{{ inputs.tenantId }}",
                "subscriptionId": "{{ inputs.subscriptionId }}"
              }
            },
            {
                "type": "AWS_CREDS",
                "awsCreds": {
                    "accessKey": "{{ inputs.accessKey }}",
                    "secretKey": "{{ inputs.secretKey }}",
                    "accessToken": "{{ inputs.accessToken }}"
                }
            }
          ]

backend_credentials: são utilizadas pelo Terraform e pela StackSpot para salvar o código IaC gerado durante o deploy, assim como para definir onde será salvo o arquivo de estado do Terraform (tfstate). Diferente da cloud_credentials, você deve usar apenas um provedor ou outro.
features_terraform_modules (Opcional): necessário quando utilizar módulos externos.

Exemplo provedor AWS
Exemplo provedor Azure DevOps

Trecho de código dos inputs do Step
jobs:
  - id: deploy
    label: Deploys Infrastructure Plugins
    steps:
    - id: deploy
      name: stackspot-core/stackspot-deploy@5
      type: workflow
      inputs:
        authenticate_client_id: "{{ inputs.stk_client_id }}"
        authenticate_client_key: "{{ inputs.stk_client_key }}"
        repository_name: "{{ inputs.repository_name }}"
        should_skip: False
        cloud_credentials: |
          [
            {
                "type": "AWS_CREDS",
                "awsCreds": {
                    "accessKey": "{{ inputs.accessKey }}",
                    "secretKey": "{{ inputs.secretKey }}",
                    "accessToken": "{{ inputs.accessToken }}"
                }
            }
          ]
        backend_credentials: |
          {
              "type": "AWS_CREDS",
              "awsCreds": {
                  "accessKey": "{{ inputs.accessKey }}",
                  "secretKey": "{{ inputs.secretKey }}",
                  "accessToken": "{{ inputs.accessToken }}"
              }
          }
        features_terraform_modules: | # Opcional caso tenha módulos externos
          [
            {
              "sourceType": "gitHttps",
              "path": "github.com/sua-organization",
              "private": true,
              "app": "***",
              "token": "<credencial-github>"
            },
            {
              "sourceType": "terraformRegistry",
              "path": "hashicorp",
              "private": True
            }
          ]

Trecho de código dos inputs do Step
jobs:
  - id: deploy
    label: Deploys Infrastructure Plugins
    steps:
    - id: deploy
      name: stackspot-core/stackspot-deploy@5
      type: workflow
      inputs:
        authenticate_client_id: "{{ inputs.stk_client_id }}"
        authenticate_client_key: "{{ inputs.stk_client_key }}"
        repository_name: "{{ inputs.repository_name }}"
        should_skip: False
        cloud_credentials: |
          [
            {
              "type": "AZ_PRINC_SECRET",
              "azPrincSecret": {
                "clientId": "{{ inputs.clientId }}",
                "clientSecret": "{{ inputs.clientSecret }}",
                "tenantId": "{{ inputs.tenantId }}",
                "subscriptionId": "{{ inputs.subscriptionId }}"
              }
            }
          ]
        backend_credentials: |
          {
            "type": "AZ_PRINC_SECRET",
            "azPrincSecret": {
              "clientId": "{{ inputs.clientId }}",
              "clientSecret": "{{ inputs.clientSecret }}",
              "tenantId": "{{ inputs.tenantId }}",
              "subscriptionId": "{{ inputs.subscriptionId }}"
            }
          }
        features_terraform_modules: | # Optional caso tenha modulos externos
          [
            {
              "sourceType": "gitHttps",
              "path": "github.com/sua-organization",
              "private": true,
              "app": "***",
              "token": "<credencial-github>"
            },
            {
              "sourceType": "terraformRegistry",
              "path": "hashicorp",
              "private": True
            }
          ]

Depois de configurar o seu Workflow de deploy, publique o Workflow no seu Estúdio para utilizá-lo nos seus deploys.

Passo 4. Configurar sua pipeline para executar o Workflow

Para executar um Workflow em seu fluxo de CI/CD, prepare a sua pipeline com a StackSpot CLI, por exemplo:

1. Download da CLI

Exemplo de script de download da CLI
shell: |
    curl \
    --fail \
    --http2-prior-knowledge \
    --location \
    --output /tmp/stk.deb \
    --silent \
    --show-error \
    --tlsv1.3 \
    https://stk.stackspot.com/installer/linux/stk.deb

2. Instalação

Exemplo de script de instalação da CLI
script: |
    sudo dpkg --install /tmp/stk.deb || echo "Installation failed with exit code: $?"

3. Autenticação

Exemplo de script de autenticação da CLI
script: |
    $HOME/.stk/bin/stk login --client-id ${{ secrets.CLIENT_ID }} --client-key ${{ secrets.CLIENT_KEY }} --realm ${{ secrets.CLIENT_REALM }}

Acesse pasta onde está arquivo .stk (da Aplicação ou Infraestrutura) e execute o comando stk deploy app | infra usando o parâmetro --workflow, além de todos os outros parâmetros obrigatórios do comando e os parâmetros utilizados pelo Workflow:

Exemplo de script para executar o comando da CLI para o deploy.
cd /< pasta-da-infraestrutura-ou-aplicação-que-contem-.stk > \

export BACKEND_CONFIG='{"type":"AZURERM","azurerm":{"tfstate":{"storageAccountName":"<tfstate-storage-account>","containerName":"<tfstate-container>","resourceGroup":"<resource-group>"},"iac":{"storageAccountName":"<iac-storage-account>","containerName":"<iac-container>","resourceGroup":"<resource-group>"}}}'

stk deploy [app|infra] \
    --workflow <seu-studio>/<seu-workflow>@<version> \
    --version <input.version> \
    -bc "$BACKEND_CONFIG" \
    --environment "<environt-name>" \
    -rs \
    -q \
    --repository_name "<app-infra-repository_name>" 
    --stk_client_id "<stk_client_id>" /
    --stk_client_key "<stk_client_key>" /
    --clientId "<clientId>" /
    --clientSecret "<clientSecret>" /
    --tenantId "<tenantId>" /
    --subscriptionId "<subscriptionId>" /
    --accessKey "<accessKey>" /
    --secretKey "<secretKey>" /
    --accessToken "<accessToken>" /
    --repository_name "<repository_name>" /

Usar Proxy para o Docker Image

Caso o ocorra algum erro de rate limit do Docker, adicione ao seu Workflow de deploy a variável container_url com o proxy do seu recurso que vai armazenar a imagem Docker.

Exemplo:

jobs:
  - id: deploy
    label: Deploys Infrastructure Plugins
    steps:
    - id: deploy
      name: stackspot-core/stackspot-deploy@5
      type: workflow
      inputs:
        ...
        container_url: "ECR-proxy/copy-image:latest"
        ...

Referências

Lista de inputs para o Deploy:

Inputs do comando stk deploy app/infra

Parâmetro	Descrição	Exemplo
`--workflow`	Executa o deploy via workflow/pipeline	-
`-e`, `--environment`	Nome do ambiente de deploy	"dev"
`-v`, `--version`	Versão da aplicação/infraestrutura	"1.0.0"
`-bc/--backend-config`	Objeto JSON com as configurações do Deploy.	"BACKEND_CONFIG"
`-rs`	Reporta o status da execução do Workflow	-
`-q`	Modo não interativo. Não irá perguntar por parâmetros não informados.	-
`-h`	Exibe ajuda do comando e sai.	-

Atualmente a gente suporta duas opções para salvar o tfstate e o IaC (Infrastructure as Code) gerado.

AWS S3
Azure Blob Storage

O Input -bc/--backend-config define em qual bucket ou Blob Storage

Exemplo JSON AWS S3
Exemplo JSON Azure Backend

{
    "type": "S3",
    "s3": { 
        "iac" : {
            "bucket": "",
            "region": ""
        },
        "tfstate": {
            "bucket": "",
            "region": "" 
        }
    }
}

Uso
stk deploy infra
  -bc '{"type":"S3","s3":{"iac":{"bucket":"","region":""},"tfstate":{"bucket":"","region":""}}}'

{
    "type": "AZURERM",
    "azurerm": {
        "iac" : {
            "storageAccountName": "",
            "containerName": "",
            "resourceGroup": ""
        },
        "tfstate": {
            "storageAccountName": "",
            "containerName": "",
            "resourceGroup": ""
        }
    }
}

Uso
stk deploy infra
  -bc '{"type":"AZURERM","azurerm":{"tfstate":{"storageAccountName":"","containerName":"","resourceGroup":""},"iac":{"storageAccountName":"","containerName":"","resourceGroup":""}}}'

Inputs do Workflow `stackspot-core/stackspot-deploy`

Nome	Tipo	Descrição	Obrigatório
`base_path_output`	String	Caminho base para os arquivos de saída. Padrão: "`.`".	Não
`path_to_mount`	String	Caminho a ser montado como volume no container. Padrão: "`.`".	Não
`authenticate_client_id`	String	Client ID para autenticação. (Pode ser definido pela variável de ambiente: `STK_CLIENT_ID`)	Sim
`authenticate_client_key`	Password	Client Key para autenticação. (Pode ser definido pela variável de ambiente: `STK_CLIENT_KEY`)	Sim
`backend_credentials`	Password	Credenciais em JSON para o Backend do Terraform (veja as notas para a estrutura do JSON)	Sim
`cloud_credentials`	Password	Credenciais em JSON para o Deploy (veja as notas para a estrutura do JSON)	Sim
`features_release_localexec`	String	Habilita ou desabilita o “`local exec`” do terraform. Padrão: `False`.	Não
`features_terraform_logprovider`	String	Nível de log para o provider do Terraform. Padrão: info.	Não
`features_level_log`	String	Nível geral de log. Padrão: info.	Não
`parallelism`	int	Quantos recursos o Terraform deve processar ao mesmo tempo. Padrão: `10`.	Não
`container_url`	String	Imagem Docker utilizada pelo EDP Deploy para executar o deploy. Padrão: `stackspot/runtime-job-unified:latest`	Não
`should_skip`	Bool	Se for definido como `true`, ele verifica se houve alguma mudança no Manifesto. Caso ele não tenha sido alterado, o deploy será definido como `SKIPPED` e não aplicará os Plugins de Infraestrutura na nuvem.	Não
`features_terraform_modules`	Password	Configuração dos módulos Terraform. Valor de exemplo: `[{"sourceType":"gitHttps","path":"github.com/*-corp","private":true,"app":"","token":"**"},{"sourceType":"terraformRegistry","path":"hashicorp","private":false}]`.	Não

Como configurar os deployments de Self-Hosted usando o StackSpot Workflow

Pré-requisitos

Como criar um StackSpot Workflow para Deploy

Passo 1. Crie o Workflow para o deploy

Passo 2. Adicione os inputs do seu provedor no Workflow de deploy

Passo 3. Crie o Job e Step para executar o deploy

Passo 4. Configurar sua pipeline para executar o Workflow

Usar Proxy para o Docker Image

Referências

Lista de inputs para o Deploy:

Inputs do Workflow stackspot-core/stackspot-deploy

Inputs do Workflow `stackspot-core/stackspot-deploy`