Skip to main content
Version: 1.15

Using Loft in CI/CD Pipelines

When using Loft in a CI/CD pipeline to create namespaces and virtual cluster, there are couple of things to consider:

  1. You might want to generate your kube configs manually
  2. You may want to use the offical loftsh/loft-ci image in a containerized CI/CD pipeline
  3. You definitely want to authenticate using Access Keys in either case
  4. If using GitHub Actions for CI/CD see the section on Using GitHub Actions
  5. If using GitLab for CI/CD see Using GitLab CI/CD Pipelines

Authentication & Cluster Access​

You can easily construct a kube config that can be used directly in any external CI/CD pipeline or tool to access a space, connected cluster or vcluster directly. For this you'll only need an access key.

Then you can create a kube config in this format:

Create a kubeconfig.yaml with:

apiVersion: v1
kind: Config
clusters:
- cluster:    
    # Optional if untrusted certificate
    # insecure-skip-tls-verify: true
    server: https://my-loft-domain.com/kubernetes/cluster/$CLUSTER
  name: loft
contexts:
- context:
    cluster: loft
    namespace: $SPACE
    user: loft
  name: loft
current-context: loft
users:
- name: loft
  user:
    token: $ACCESS_KEY

Replace the $ACCESS_KEY with your generated access key, $CLUSTER with the name of the connected kubernetes cluster the space was created in and $SPACE with the name of the space. You can now use this kube config with any external applications such as kubectl or terraform.

Then run any command in the space with:

kubectl --kubeconfig kubeconfig.yaml get pods

Authentication​

Create Access Keys​

Loft UI - Profile: Create Access Key

Using the Container Image​

When using Loft in a CI/CD pipeline that runs based on containers, you can use the official loft-ci image either as a base image or directly.

This image is based on alpine and contains:

This is what the Dockerfile looks like:

FROM devspacesh/devspace:5

# Add helm
RUN wget -O helm.tar.gz https://get.helm.sh/helm-v3.3.3-linux-amd64.tar.gz \
 && tar -zxvf helm.tar.gz \
 && mv linux-amd64/helm /bin/helm

# Add Loft CLI (same version as the tag of this image)
COPY release/loft-linux-amd64 /bin/loft
RUN chmod +x /bin/loft

Login with Access Keys​

loft login https://my-loft.url.tld --access-key [ACCESS_KEY] # Replace URL with your own

Integrations​

GitHub Actions​

Loft provides the following GitHub Actions for use in workflows:

Spaces for Pull Requests​

These examples show how to create and delete Spaces for pull requests.

This example shows how to create and delete a space to test an application named my-app for pull requests.

# .github/workflows/prs.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - 'main'
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install Loft CLI
        uses: loft-sh/setup-loft@main
        with:
          url: ${{ secrets.LOFT_URL }}
          access-key: ${{ secrets.LOFT_ACCESS_KEY }}
      - name: Create Space for PR
        uses: loft-sh/create-space@main
        with:
          name: pr-${{ github.event.pull_request.number }}-${{ github.sha }}-${{ github.run_id }}
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status -n pr-${{ github.event.pull_request.number }}-${{ github.sha }}-${{ github.run_id }} deployments/my-app
      - name: Run Tests
        run: make e2e
      - name: Delete PR Space
        uses: loft-sh/delete-space@main
        with:
          name: pr-${{ github.event.pull_request.number }}-${{ github.sha }}-${{ github.run_id }}

Explanation:

  1. The Setup Loft action is used to install the Loft CLI and login using the provided url and access-key.
  2. The Create Space action is used to create a unique space using information about the pull request. This will automatically configure the kube context for the following steps.
  3. The next step deploys the application using the runner provided kubectl and manifests located under ./kubernetes.
  4. Before running tests, we use kubectl to wait for the my-app deployment to become ready.
  5. Now we run the end-to-end tests. In this example we're using make to run tests, but the command should be customized for your testing framework.
  6. Finally, the Delete Space GitHub Action is used to delete the pull request's space.

Virtual Clusters for Pull Requests​

These examples show how to create and delete Virtual Clusters for pull requests.

This example shows how to create and delete a virtual cluster for testing an application named my-app on pull requests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - 'main'
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install Loft CLI
        uses: loft-sh/setup-loft@main
        with:
          url: ${{ secrets.LOFT_URL }}
          access-key: ${{ secrets.LOFT_ACCESS_KEY }}
      - name: Create Virtual Cluster for PR
        uses: loft-sh/create-vcluster@main
        with:
          name: pr-${{ github.event.pull_request.number }}-${{ github.sha }}-${{ github.run_id }}
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status deployments/my-app
      - name: Run Tests
        run: make e2e
      - name: Delete PR Virtual Cluster
        uses: loft-sh/delete-vcluster@main
        with:
          name: pr-${{ github.event.pull_request.number }}-${{ github.sha }}-${{ github.run_id }}

Explanation:

  1. The Setup Loft action is used to install the Loft CLI and login using the provided url and access-key.
  2. The Create Virtual Cluster action is used to create a unique virtual cluster using information about the pull request. This will automatically configure the kube context for the following steps.
  3. The next step deploys the application using the runner provided kubectl and manifests located under ./kubernetes.
  4. Before running tests, we use kubectl to wait for the my-app deployment to become ready.
  5. Now we run the end-to-end tests. In this example we're using make to run tests, but the command should be customized for your testing framework.
  6. Finally, the Delete Virtual Cluster GitHub Action is used to delete the virtual cluster.

GitLab CI/CD​

When using Loft with GitLab you can use the official loft-ci image as either a base image or directly. See Using the Container Image for details on the available tools. If additional tooling is needed for your CI/CD process, a custom image can be created.

Spaces for Merge Requests​

This example shows how to create and delete a Space for running end-to-end tests for the default branch and merge requests. It assumes you have configured CI/CD variables LOFT_URL and LOFT_ACCESS_KEY.

image: loftsh/loft-ci

stages:
  - test

e2e:
  rules:
    - if: $CI_MERGE_REQUEST_IID
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  stage: test
  before_script:
    - loft login $LOFT_URL --access-key $LOFT_ACCESS_KEY
    - loft create space "${CI_PROJECT_NAME}-${CI_COMMIT_SHORT_SHA}-${CI_PIPELINE_ID}"
    - apk add go make
  script:
    - kubectl apply -Rf ./kubernetes
    - kubectl rollout status deployments/my-app
    - make e2e
  after_script:
    - loft delete space "${CI_PROJECT_NAME}-${CI_COMMIT_SHORT_SHA}-${CI_PIPELINE_ID}"

Explanation:

  1. The loftsh/loft-ci image is used for all pipeline jobs and provides the loft CLI, the devspace CLI, and kubectl.
  2. The before_script first logs in to loft using the $LOFT_URL and $LOFT_ACCESS_KEY variables that you defined in GitLab. See the GitLab docs for more information
  3. The before_script then creates a space using predefined GitLab variables to create a unique name for the space.
  4. Next before_script installs some additional tooling needed to run the end-to-end tests. For more complex scenarios creating a custom image is recommended.
  5. Then the script section uses kubectl to deploy the application to the space and waits for the my-app deployment to become ready. make is then used to run an end-to-end test suite.
  6. Finally after_script deletes the space. By using after_script we can ensure the space is deleted even if the tests fail.

Virtual Clusters for Merge Requests​

This example shows how to create and delete a Virtual Cluster for running end-to-end tests for the default branch and merge requests. It assumes you have configured CI/CD variables LOFT_URL and LOFT_ACCESS_KEY.

image: loftsh/loft-ci

stages:
  - test

e2e:
  rules:
    - if: $CI_MERGE_REQUEST_IID
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  stage: test
  before_script:
    - loft login $LOFT_URL --access-key $LOFT_ACCESS_KEY
    - loft create vcluster "${CI_PROJECT_NAME}-${CI_COMMIT_SHORT_SHA}-${CI_PIPELINE_ID}"
    - apk add go make
  script:
    - kubectl apply -Rf ./kubernetes
    - kubectl rollout status deployments/my-app
    - make e2e
  after_script:
    - loft delete vcluster "${CI_PROJECT_NAME}-${CI_COMMIT_SHORT_SHA}-${CI_PIPELINE_ID}" --delete-space

Explanation:

  1. The loftsh/loft-ci image is used for all pipeline jobs and provides the loft CLI, the devspace CLI, and kubectl.
  2. The before_script first logs in to loft using the $LOFT_URL and $LOFT_ACCESS_KEY variables that you defined in GitLab. See the GitLab docs for more information
  3. The before_script then creates a virtual cluster using predefined GitLab variables to create a unique name.
  4. Next before_script installs some additional tooling needed to run the end-to-end tests. For more complex scenarios creating a custom image is recommended.
  5. Then the script section uses kubectl to deploy the application to the space and waits for the my-app deployment to become ready. make is then used to run an end-to-end test suite.
  6. Finally after_script deletes the virtual cluster, and passes --delete-space to ensure the corresponding space for the cluster is deleted. By using after_script we can ensure the space is deleted even if the tests fail.