Usar o Runtimes Self-Hosted GitHub
Nesta seção, você encontra como usar o Runtimes Self-Hosted na sua pipeline de deploy.
Pré-requisitos
Esta configuração é feita apenas pelo Account Holder, Account Admin ou SRE.
- Pessoa usuária com permissão de escrita em um repositório do GitHub;
- Ter acesso a uma Conta AWS;
- Gerar Credencial de Serviço ou Token de Acesso Pessoal StackSpot;
É indicado dar preferência ao uso da Credencial de Serviço.
- Cadastre as credenciais como segredos (secrets) no GitHub;
- O Runner do provedor (GitHub) deve suportar Docker in Docker;
- É necessário ter um Bucket na AWS para salvar os TFstates, e um para salvar os IaC gerados pelos Plugins (podem ser o mesmo Bucket).
- Ter uma Aplicação ou Infraestrutura criada e registrada na StackSpot.
Como usar o Self-Hosted
Antes de usar o Runtimes Self-hosted na sua Pipeline do GitHub, você deve criar e configurar uma pipeline para executar algumas GitHub Actions.
Confira os passos a seguir:
1. Cadastre sua credencial como segredo no GitHub
Use os segredos da etapa:
Client IDcomoCLIENT_IDno segredo;Client KeycomoCLIENT_KEYno segredo;RealmcomoCLIENT_REALMno segredo;
Para mais detalhes, siga o uso de segredos na documentação do GitHub Actions.
Defina seus segredos da AWS usando também os segredos do GitHub Actions.
2. Implemente o exemplo do workflow na sua pipeline
Passo 1. Crie um novo arquivo de workflow em seu repositório. Por exemplo: .github/workflows/workflow_example.yml.
Passo 2. Copie e cole o exemplo a seguir em seu novo arquivo de workflow:
name: Stk Self Hosted
on:
push:
branches:
- main
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: false
jobs:
orquestrar_e_planejar:
runs-on: <self-hosted-runner> # Aqui você deve usar um runner que possa acessar sua conta na nuvem
outputs:
apply_tasks: ${{ steps.orquestrar_e_planejar.outputs.apply_tasks }}
run_id: ${{ steps.orquestrar_e_planejar.outputs.run_id }}
steps:
- name: Checkout code
uses: actions/checkout@v2
- name: Deployar Infrastructure
uses: stackspot/edp-deploy-orchestration-action@v1.2
id: orquestrar_e_planejar
with:
TFSTATE_BUCKET_NAME: "000000000000-tfstate-bucket"
TFSTATE_BUCKET_REGION: sa-east-1
IAC_BUCKET_NAME: "000000000000-iac-bucket"
IAC_BUCKET_REGION: sa-east-1
WORKSPACE: "meu-workspace"
ENVIRONMENT: "prod"
VERSION: "v1.0.0"
REPOSITORY_NAME: ${{ github.event.repository.name }}
PATH_TO_MOUNT: /home/runner/_work/${{ github.event.repository.name }}/${{ github.event.repository.name }}
WORKDIR: /caminho/para/pasta/pai-da-.stk # Caso seu repositório tenha um .stk que não esteja na pasta raiz do repositório
STK_CLIENT_ID: ${{ secrets.CLIENT_ID }}
STK_CLIENT_SECRET: ${{ secrets.CLIENT_SECRET }}
STK_REALM: <realm>
AWS_IAM_ROLE: ${{ secrets.AWS_ROLE_ARN }}
AWS_REGION: sa-east-1
FEATURES_TERRAFORM_MODULES: >-
[
{
"sourceType": "gitHttps",
"path": "github.com/stack-spot",
"private": true,
"app": "app",
"token": "token"
},
{
"sourceType": "terraformRegistry",
"path": "hashicorp/stack-spot",
"private": false
}
]
aprovar_plano_aplicar:
name: Deploy
needs: [orquestrar_e_planejar]
runs-on: <self-hosted-runner> # Aqui você deve usar um runner que possa acessar sua conta na nuvem
environment: prod # Aqui você define os ambientes nos quais o usuário deve aprovar as alterações planejadas a partir da etapa de orquestração
steps:
- name: Service Provision
id: run-task
uses: stack-spot/runtime-tasks-action@v2.1
if: needs.orquestrar_e_planejar.outputs.run_id != ''
with:
RUN_ID: ${{ needs.orquestrar_e_planejar.outputs.run_id }}
TASK_LIST: ${{ needs.orquestrar_e_planejar.outputs.apply_tasks }}
REPOSITORY_NAME: ${{ github.event.repository.name }}
PATH_TO_MOUNT: /home/runner/_work/${{ github.event.repository.name }}/${{ github.event.repository.name }}
AWS_REGION: sa-east-1
AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }}
FEATURES_TERRAFORM_MODULES: >-
[
{
"sourceType": "gitHttps",
"path": "github.com/stack-spot",
"private": true,
"app": "app",
"token": "token"
},
{
"sourceType": "terraformRegistry",
"path": "hashicorp/stack-spot",
"private": false
}
]
CLIENT_ID: ${{ secrets.CLIENT_ID }}
CLIENT_KEY: ${{ secrets.CLIENT_SECRET }}
CLIENT_REALM: <realm>
cancel: # caso algo na sua pipeline quebre ou alguém a cancele no meio do deployment, é necessário executar esta ação para informar à StackSpot que ocorreu um erro e evitar que os próximos deployments sejam bloqueados
runs-on: ubuntu-latest
needs: [orquestrar_e_planejar, aprovar_plano_aplicar]
if: ${{ always() && (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) }}
steps:
- name: Cancel run
if: needs.orquestrar_e_planejar.outputs.run_id != ''
id: run-cancel
uses: stack-spot/runtime-cancel-run-action@v1
with:
CLIENT_ID: ${{ secrets.CLIENT_ID }}
CLIENT_KEY: ${{ secrets.CLIENT_SECRET }}
CLIENT_REALM: <realm>
RUN_ID: ${{ needs.orquestrar_e_planejar.outputs.run_id }}
3. Funcionamento das Actions
Processo de Deploy atual da StackSpot
Deploy StackSpot Unificado BETA
Cancel Run Action
Esta Action atua como uma proteção contra falhas para evitar travamentos nos processos. A StackSpot gerencia cada deploy para prevenir deploy paralelizados e outras ações que possam causar problemas aos usuários.
Se uma pipeline for cancelada manualmente ou um runner falhar durante o deploy, é necessário informar aos serviços da StackSpot que o deploy foi abortado. Caso contrário, futuros deploys poderão ser bloqueados.
É obrigatório utilizar o if: always().
cancel:
needs: [orquestrar_e_planejar, aprovar_plano_aplicar]
if: ${{ always() && (contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')) }}
# Executará sempre que houver um erro ou a pipeline for cancelada
steps:
- name: Cancel run
if: needs.orquestrar_e_planejar.outputs.run_id != ''
id: run-cancel
uses: stack-spot/runtime-cancel-run-action@v1
with:
CLIENT_ID: ${{ secrets.CLIENT_ID }}
CLIENT_KEY: ${{ secrets.CLIENT_SECRET }}
CLIENT_REALM: <realm>
RUN_ID: ${{ needs.orquestrar_e_planejar.outputs.run_id }}
Agora você está pronto para configurar e executar a Action da StackSpot em sua pipeline!
Para saber mais sobre os inputs das Action, confira os repositórios:
4. Inputs especiais
AWS_IAM_ROLE
- Descrição: o AWS IAM Role a ser utilizado para deploy de Infraestrutura.
- Observação: se os inputs
AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYeAWS_SESSION_TOKENforem fornecidos, eles não devem ser utilizados. A Action assumirá automaticamente a role no runner.
AWS_ACCESS_KEY_ID
- Descrição: o AWS Access Key ID para deploy de Infraestrutura.
- Observação: deve ser fornecido apenas se
AWS_IAM_ROLEnão for utilizada.
AWS_SECRET_ACCESS_KEY
- Descrição: o AWS Secret Access Key para deploy de Infraestrutura.
- Observação: deve ser fornecido apenas se
AWS_IAM_ROLEnão for utilizada.
AWS_SESSION_TOKEN
- Descrição: o AWS Session Token para deploy de Infraestrutura.
- Observação: deve ser fornecido apenas se
AWS_IAM_ROLEnão for utilizada.
Regras de Uso
-
Uso do
AWS_IAM_ROLE:- Se o input
AWS_IAM_ROLEfor fornecido, a Action assumirá automaticamente a role no runner. Neste caso, não forneça os inputsAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYeAWS_SESSION_TOKEN. - Certifique-se de que o runner possui permissões para assumir a role fornecida.
- Se o input
-
Uso de Credenciais AWS Diretas:
- Se você optar por não utilizar o
AWS_IAM_ROLE, forneça diretamente os inputsAWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEYeAWS_SESSION_TOKEN. - Certifique-se de que as credenciais fornecidas possuem as permissões necessárias para acessar a AWS.
- Se você optar por não utilizar o
Observações
- Recomenda-se o uso de
AWS_IAM_ROLEpara maior segurança, pois elimina a necessidade de utilizar credenciais sensíveis diretamente. - Se ambos os métodos forem configurados (fornecendo
AWS_IAM_ROLEe as credenciais diretas), a Action dará prioridade ao uso doAWS_IAM_ROLEe desconsiderará as credenciais diretas.
Uso de Plugins de Infraestrutura Forkados com Self-Hosted
Confira como configurar o uso de Plugins de Infraestrutura forkados em um ambiente Self-Hosted.
Path dos Plugins Forkados
Quando um Plugin de Infraestrutura é forkado, os templates de deploy são armazenados no seguinte caminho dentro do repositório: .stk/FORKED_PLUGINS/<plugin-alias>
Para que o deploy funcione corretamente, é necessário garantir que o Docker tenha acesso à pasta onde estão os arquivos do repositório, incluindo os Plugins que foram forkados.
O input PATH_TO_MOUNT deve ser configurado para apontar para o diretório onde esses arquivos estão localizados. Isso é essencial para garantir que o Docker tenha acesso aos arquivos do repositório, incluindo os Plugins forkados.
Confira a seguir um Exemplo de Configuração do input no GitHub Actions:
WITH:
PATH_TO_MOUNT: /home/runner/_work/${{ github.event.repository.name }}/${{ github.event.repository.name }}
Este caminho aponta para os arquivos do repositório após a execução de um checkout no workflow.
Observações
- Certifique-se de que o repositório foi clonado corretamente no runner antes de configurar o
PATH_TO_MOUNT. - O runner precisa ter permissões adequadas para acessar os arquivos do repositório e o diretório
.stk/FORKED_PLUGINS/<plugin-alias>. - Caso o caminho padrão não seja adequado para o seu ambiente, ajuste o valor de
PATH_TO_MOUNTpara refletir o local correto dos arquivos do repositório. Com essa configuração, o deploy de Plugins forkados será realizado com sucesso em um ambiente Self-Hosted.
Acompanhar o status do deploy
É possível acompanhar o status do deploy através de duas formas:
1. Localmente no STK CLI
Passo 1. Execute o comando para acessar o Workspace da sua Aplicação:
stk use workspace <workspace-slug>
Passo 2. Executando o comando para acompanhar:
stk deploy status <deploy-id> --watch
Você encontra o deploy id ao finalizar a execução do deploy na sua pipeline. Deve aparecer como no exemplo a seguir:
RUN DEPLOY_SELF_HOSTED successfully started with ID: 01J9V6MWFTWQ392331QBCS46KQ
2. Via Portal da StackSpot EDP
Confira o passo a passo:
Passo 1. Acesse o seu Workspace no Portal da StackSpot EDP;
Passo 2. Acesse sua Aplicação ou Infraestrutura;
Passo 3. No menu lateral, selecione o ambiente onde você fez o deploy;
Passo 4. Vá para a seção de 'Atividades' e clique na aba 'Deploy Self-hosted'.
Próximos passos
Esta página foi útil?