Usar o Runtimes Self-Hosted Azure DevOps

In this section, you'll find how to use a Self-Hosted runner in your deployment pipeline.

◀

Account Configuration

You are here!

Deployment Configuration

Create Content

Use Content

▶

Requirements

• A user with write permission to an Azure DevOps repository and permission to use Azure DevOps Pipelines;
• Access to an AWS Account;
• Generate a Service Credential or StackSpot Personal Access Token;

tip

We recommend using the Service Credential for enhanced security and streamlined management.

• The provider's Runner must support Docker in Docker;
• You must have an Application or Infrastructure created and registered in StackSpot.
• You must have two AWS buckets to store the generated IaCs and managed TFstates (they can be the same bucket).

How to use a Self-Hosted Runtimes

To use the Runtimes Self-hosted in Azure Pipelines, you must first create and configure a pipeline to execute a StackSpot Action.

Follow the steps below:

Implement the Workflow example in your pipeline

Step 1. Create a new Workflow file in your repository. For example: stackspot_deploy.yml;

Step 2. Copy and paste the example below into your new Workflow file:

Pipeline Manifest for StackSpot Action

stackspot_deploy.yml

trigger:
  - none

name: Stackspot Deploy

pool:
  name: your-runner-of-choice

stages:
  - stage: Deploy
    displayName: Deploying Using Runtimes
    jobs:
      - job: InstallCLI
        displayName: "Installing CLI"
        steps:
          - bash: | # Installs AWS CLI
              if ! command -v aws &> /dev/null
              then
                  echo "AWS CLI not found. Installing..."
                  curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
                  apt install -y unzip
                  unzip awscliv2.zip
                  sh ./aws/install
              else
                  echo "AWS CLI is already installed."
              fi
            displayName: Check and Install AWS CLI
          - bash:
              | # Assumes the role that has permission to create/update aws services
              aws sts assume-role \
                --role-arn <role-arn> \
                --region <region> \
                --role-session-name azure-deploy \
                --output json >> ./cred.json

              # Output the variables for use in subsequent steps
              echo "##vso[task.setvariable variable=AWS_ACCESS_KEY_ID;isSecret=true]$(jq -r '.Credentials.AccessKeyId' cred.json)"
              echo "##vso[task.setvariable variable=AWS_SECRET_ACCESS_KEY;isSecret=true]$(jq -r '.Credentials.SecretAccessKey' cred.json)"
              echo "##vso[task.setvariable variable=AWS_SESSION_TOKEN;isSecret=true]$(jq -r '.Credentials.SessionToken' cred.json)"
            displayName: STS

          - bash: | # Installs Stackspots CLI to create deployment
              apt-get -qq update
              apt-get install -y curl git 

              # Clean CLI Install
              rm -rf $HOME/.stk

              # Faz o download e instala o STK CLI
              curl -fsSL https://stk.stackspot.com/install.sh | bash

              # Verifica a instalação do STK CLI
              $HOME/.stk/bin/stk --version
            displayName: Installing CLI
          - bash:
              | # Logins using your credentials - ID and Key should be secrets
              $HOME/.stk/bin/stk login --client-id $(STK_CLIENT_ID) --client-key $(STK_CLIENT_KEY) --realm <realm>
              $HOME/.stk/bin/stk use workspace runtime
            displayName: Logging In
          - checkout: self
            displayName: "Checking out repo"
          - bash: |
              export INPUTS_CLIENT_ID=$(STK_CLIENT_ID)
              export INPUTS_CLIENT_KEY=$(STK_CLIENT_KEY)
              export INPUTS_CLIENT_REALM=<realm>
              export INPUTS_TF_STATE_REGION=sa-east-1
              export INPUTS_IAC_REGION=sa-east-1
              export INPUTS_AWS_REGION=sa-east-1
              export INPUTS_IAC_BUCKET_NAME=000000000000-your-bucket-to-save-generated-iac
              export INPUTS_TF_STATE_BUCKET_NAME=000000000000-your-bucket-to-save-managed-tfstates
              export INPUTS_AWS_SECRET_ACCESS_KEY=$(AWS_SECRET_ACCESS_KEY)
              export INPUTS_AWS_ACCESS_KEY_ID=$(AWS_ACCESS_KEY_ID)
              export INPUTS_AWS_SESSION_TOKEN=$(AWS_SESSION_TOKEN)
              export INPUTS_ENVIRONMENT=<deployment-environment>
              export INPUTS_REPOSITORY_NAME=$(Build.Repository.Name)
              export INPUTS_VERSION_TAG=$(System.JobId)-$(System.JobAttempt)
              export INPUTS_DYNAMIC_INPUTS="--additional-input <additional-input-value>"

              # Download Deploy action 
              git clone https://github.com/stack-spot/workflow-stackspot-actions-runtime-selfhosted.git
              cd workflow-stackspot-actions-runtime-selfhosted
              export run_action_path=$(pwd)
              cd ..

              cd ./dot-stk-folder-parent
              $HOME/.stk/bin/stk run action $run_action_path --workflow_type deploy --non-interactive
            displayName: Deploying

Step 3. Create a pipeline based on this workflow in your repository;

Step 4. Add the variables STK_CLIENT_ID and STK_CLIENT_KEY from your service credential as secrets:

About the Manifest

In this pipeline manifest, you will find the necessary configuration to execute a StackSpot Action on an Ubuntu-based image. If you use a different image type, adjust the commands as needed.

This manifest will follow the steps below to ensure the Action works correctly:

1. Install the necessary dependencies:

• Curl;
• Git;
• STK CLI;
• AWS CLI: if the runner does not have direct access to the Clouds.
• jq if you need to extract AWS credentials.

2. (Optional) Clone the official Action repository: You can directly clone the public repository of the StackSpot Self-Hosted Runtimes Action: GitHub Repository.

tip

StackSpot Action This step is optional. You can clone and publish the repository to your StackSpot account, allowing control and usage by semantic versioning in the run action command.

3. Definition of Action inputs: This section explains how to define the inputs for StackSpot Actions using environment variables. If you prefer, you can modify the file to pass the inputs directly in the run action command. For more details, refer to the Run Actions documentation.

4. Login to StackSpot: Use your service credentials to log in to StackSpot.

5. Using a StackSpot Workspace: Make sure you are using the correct StackSpot Workspace, which corresponds to the Application or Infrastructure where you will perform the deployment, destruction, or rollback.

6. Execution of the StackSpot Runtimes Self-Hosted Action: The Action will be executed in the folder of the Application or Infrastructure where the deployment, destruction, or rollback takes place. It is crucial that the Action is located in the correct folder; otherwise, the execution will fail.

What the StackSpot Runtimes Self-Hosted Action Does

1. Analyzes the applied plugins within the Infrastructure or Application. The Runtimes API orchestrates the provisioning order, producing a list of tasks for the next Actions to execute.

2. Generates the Infrastructure as Code (IaC) using Terraform for the plugin applied to the Infrastructure or Application, replacing the variables in the Plugin template.

3. Executes the DEPLOY_SELF_HOSTED task, which downloads and applies the IaC (Terraform) to the client's Infrastructure. The generated tfstate file is stored in the configured bucket, allowing the process to continue.

4. When a Plugin is removed, a DESTROY_SELF_HOSTED task is generated, and the Action performs a Terraform destroy on the Plugin's tfstate.

5. Notifies the Runtimes API if a pipeline execution is interrupted, whether due to manual cancellation, failure in a custom step, or runner shutdown. This ensures that the API is aware of the error, preventing future pipeline executions for the same Application and environment from being blocked. Without this notification, the API would block new executions, requiring manual intervention. This Action ensures that the execution flow does not get stuck.

Now, you can configure and execute the StackSpot Action in your pipeline!

Monitor the deployment status

You can monitor the deployment status in two ways:

1. Locally via STK CLI

Step 1. Run the command to access your Application's Workspace:

stk use workspace <workspace-slug>

Step 2. Run the following command to monitor the status:

stk deploy status <deploy-id> --watch

You can find the deploy id during the deployment execution in your pipeline. See the example below:

RUN DEPLOY_SELF_HOSTED successfully started with ID: 01J9V6MWFTWQ392331QBCS46KQ

Available Inputs

Mandatory Inputs

• INPUT_AWS_ACCESS_KEY_ID mandatory

  • AWS Access Key ID.

• INPUT_AWS_SECRET_ACCESS_KEY mandatory

  • AWS Secret Access Key.

• INPUT_AWS_SESSION_TOKEN mandatory

  • AWS Session Token.

• INPUT_CLIENT_ID mandatory

  • Client ID for authentication (Service Credential).

• INPUT_CLIENT_KEY mandatory

  • Client Key for authentication (Service Credential).

• INPUT_CLIENT_REALM mandatory

  • Client Realm for authentication (Service Credential).

• INPUT_REPOSITORY_NAME mandatory

  • Repository name.

• INPUT_AWS_REGION mandatory

  • AWS Region for deployment.

• INPUTS_IAC_REGION mandatory

  • Region for the following IAC Bucket.

• INPUTS_IAC_BUCKET_NAME mandatory

  • S3 bucket name to store the IaC generated by the Plugins.

• INPUTS_TF_STATE_REGION mandatory

  • Region for the following TFstate Bucket.

• INPUTS_TF_STATE_BUCKET_NAME mandatory

  • S3 bucket name to store the managed Terraform TFstates.

• INPUTS_ENVIRONMENT mandatory

  • The deployment environment is registered in the StackSpot account (e.g., dev, staging, prod).

• INPUTS_VERSION_TAG mandatory

  • Version tag to add to the deployment (e.g., v1.0.0).

    danger

    Tags cannot be reused for the same Infrastructure in the same environment.

Optional Inputs

• INPUTS_DYNAMIC_INPUTS

  • Additional dynamic inputs. Each Plugin will automatically include these dynamic inputs when requesting a deployment. (e.g., --additional-input <additional-input-value>)

• INPUT_PATH_TO_MOUNT

  • Path for mounting in Docker, in case your Plugin requires files from the repository or generated in the pipeline. This path will be mounted in the Docker working directory (workdir) and can be accessed by Terraform if necessary.
  • Default Value: .

• INPUT_TF_PARALLELISM

  • Terraform parallelism level, used only in unified deploys, defines the maximum number of simultaneous Terraform executions.
  • Default Value: 10.

• INPUT_FEATURES_LEVEL_LOG

  • StackSpot Service Log Level.

  • Default Value: info.

    danger

    Sensitive Information

    Avoid using DEBUG or TRACE modes unnecessarily, as they may expose sensitive information in the pipeline. Use them cautiously to ensure data security.

• INPUT_FEATURES_TERRAFORM_LOGPROVIDER

  • Log level for the Terraform provider.
  • Default Value: info.

• INPUT_FEATURES_RELEASE_LOCALEXEC

  • Release of the local-exec feature.
  • Default Value: False.

• INPUT_FEATURES_TERRAFORM_MODULES

  • List of Terraform modules to be used in the deployment process. If an external module is used and not included in this list, the execution will be blocked.

  • Default Value: [].

  • Input structure:

    [
      {
        "sourceType": "gitHttps",
        "path": "github.com/stack-spot",
        "private": true,
        "app": "app",
        "token": "$(tokenToClone)"
      },
      {
        "sourceType": "terraformRegistry",
        "path": "hashicorp/stack-spot",
        "private": false
      }
    ]

2. Via StackSpot EDP Portal

Follow the steps:

Step 1. Access your Workspace on the StackSpot EDP Portal;

Step 2. Access your Application or Infrastructure;

Step 3. In the menu, select the environment where you performed the deploy;

Step 4. Go to the 'Activities' section in the menu and click on the 'Self-Hosted Deploy' tab.

Next Steps

• Set up the Application deployment registration command in your pipeline;
• Set up Webhook to register repository activities of your Application on the Activities screen;
• Manage your Application.