Using Self-Hosted Runtimes GitLab

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

◀

Account Configuration

You are here!

Deployment Configuration

Create Content

Use Content

▶

Requirements

danger

Only Account Holder, Account Admin, or SRE can set up a self-hosted Runtimes.

• A user with write access to a GitLab repository;
• Have access to an AWS Account;
• Generate a Service Credential or StackSpot Personal Access Token;

tip

It is recommended that you use the Service Credential.

• Register the credentials as masked variables in GitLab;
• The provider’s runner (GitLab) must support docker in docker;
• You must have an Application or Infrastructure created and registered in StackSpot.

How to use Self-Hosted Runtimes

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

Follow the steps below:

Implement the example workflow in your pipeline

Step 1. Create a new Workflow file in your repository. For example: .github/workflows/workflow_example.yml.

Step 2. Copy and paste the following example into your new workflow file:

Pipeline Manifest for StackSpot Action

stackspot_deploy.yml

image: <your-image>

# Global variable definition
variables:
  # Refer to item 2 of the manifest description below
  WORKFLOW_REPO_URL: "https://github.com/stack-spot/workflow-stackspot-actions-runtime-selfhosted.git"

stages:
  - run_stackspot

# Common setup steps for all jobs
before_script:
  # Update the package list and install necessary dependencies
  - apt-get -qq update
  - apt-get install -y curl git

  # Download and install the STK CLI
  - curl -s -O "https://stk.stackspot.com/installer/linux/stk"
  - chmod +x stk
  - ./stk init
  
  # Set the STK CLI path for script usage
  - export STK=~/.stk/bin/stk

  # Check the STK CLI installation
  - $STK --version

stk:
  stage: run_stackspot
  script:
    
    # Clone the workflow repository
    - git clone $WORKFLOW_REPO_URL
    - cd workflow-stackspot-actions-runtime-selfhosted
    - run_action_path=$(pwd)
    - cd ..

    # Export the necessary environment variables for StackSpot
    - export INPUTS_CLIENT_ID=$STK_CLIENT_ID
    - export INPUTS_CLIENT_KEY=$STK_CLIENT_SECRET
    - export INPUTS_CLIENT_REALM=$STK_REALM
    - export INPUTS_TF_STATE_REGION=$AWS_REGION
    - export INPUTS_IAC_REGION=$AWS_REGION
    - export INPUTS_AWS_REGION=$AWS_REGION
    - export INPUTS_IAC_BUCKET_NAME=$IAC_BUCKET_NAME
    - export INPUTS_TF_STATE_BUCKET_NAME=$TF_STATE_BUCKET_NAME
    - export INPUTS_AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID
    - export INPUTS_AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY
    - export INPUTS_AWS_SESSION_TOKEN=$AWS_SESSION_TOKEN
    - export INPUTS_ENVIRONMENT=$ENVIRONMENT
    - export INPUTS_REPOSITORY_NAME=$CI_PROJECT_NAME # Reference: https://docs.gitlab.com/ee/ci/variables/predefined_variables.html
    - export INPUTS_VERSION_TAG=$CI_JOB_ID # Adjust this logic as needed

    # Authenticate with StackSpot using the provided credentials
    - $STK login --client-id $INPUTS_CLIENT_ID --client-key $INPUTS_CLIENT_KEY --realm $INPUTS_CLIENT_REALM

    # Set the workspace to be used
    - $STK use workspace $STK_WORKSPACE

    # Run the StackSpot Action
    - $STK run action $run_action_path --workflow_type deploy --non-interactive

About the manifest

In this pipeline manifest, you will find the necessary setup to execute a StackSpot Action in an Ubuntu-based image. If you are using another type of image, adjust the commands accordingly.

This manifest follows the steps below to ensure the Action runs correctly:

1. Install necessary dependencies:

   • Curl;
   • Git;
   • STK CLI.

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

   This step is optional. Feel free to clone the repository and publish it in your own StackSpot account, allowing you to control and use semantic versioning in the run action command.

3. Define Action inputs: The file provides a way to define StackSpot Action inputs via environment variables. Feel free to modify the file if you prefer to pass inputs directly into the run action command. For more information, refer to the Run Action documentation.

4. Login to StackSpot: Log in using the service credentials.

5. Use a StackSpot Workspace: Ensure you are using the correct StackSpot Workspace, corresponding to the Application or Infrastructure that will be deployed, destroyed, or rolled back.

6. Execute the StackSpot Self-Hosted Runtimes Action: The Action will be executed in the folder of the Application or Infrastructure where the deploy, destroy, or rollback will be performed. It is essential that the Action is in the correct folder; otherwise, the execution will fail.

What the StackSpot Runtimes Self-Hosted Action does:

1. Analyzes the Plugins applied to the Infrastructure or Application, and the Runtimes API orchestrates the provisioning order, returning a list of tasks for the following Actions to execute;

2. Generates the IaC (Terraform) for the Plugin applied to the Infrastructure or Application, replacing the variables from the Plugin template;

3. Executes a DEPLOY_SELF_HOSTED task, downloading and applying the IaC (Terraform) to the client's Infrastructure. The generated tfstate will be stored in the defined bucket, and the process will continue;

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

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

Now you're ready to configure and execute the StackSpot Action in your pipeline!

Important Information

To learn more about the Action inputs, visit the official repository.

Track the deployment status

You can track the deployment status in two ways:

Locally with STK CLI:

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

stk use workspace <workspace-slug>

Step 2. Run the command to track the deployment:

stk deploy status <deploy-id> --watch

You will find the deploy id at the end of the deployment execution in your pipeline. It should appear as in the following example:

RUN DEPLOY_SELF_HOSTED successfully started with ID: 01J9V6MWFTWQ392331QBCS46KQ

Via StackSpot EDP Platform

Follow the steps:

Step 1. Access your Workspace in the StackSpot Platform;

Step 2. Access your Application or Infrastructure;

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

Step 4. Go to the ‘Activities’ section in the side 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.