Skip to main content

Deploy your App using GitHub and Wayfinder

Quick-Starter Guide Series

Prerequisites​


Key Steps​

  • Create an example application in Wayfinder with a single container component
  • Create a Workspace Access Token and give it permissions
  • Configure GitHub secrets and variables for your GitHub workflow
  • Configure GitHub workflow for deployment to an ephemeral PR Preview cluster
  • Configure GitHub workflow for PR Preview Teardown on Merge
  • Configure GitHub workflow for deployment to a long-lived PROD cluster

Quick Guide​

This guide will walk you through creating an application with a single container component in Wayfinder. Following that, you'll integrate GitHub as a demonstration of version control with your application deployment manifests.

You can find example files in our .github/workloads folder.

Complete the following steps using Wayfinder's CLI or Wayfinder's Web Interface.

Step 1: Create an Application​

Applications encapsulate the elements that make up your application's deployment.

Wayfinder Create an Application
  wf create application APP-NAME -w WORKSPACE --cloud CLOUD-PROVIDER

For More Information See


Step 2: Create a Container Component​

Container components refer to the individual containers that make up an application, encapsulated within Pods, and managed by the Kubernetes platform.

Wayfinder Create a Container Component
wf create appcomponent frontend --app app1 --type container --image quay.io/appvia-wf-dev/wftoolbox:latest -w sand2

For More Information See


Step 3: Preview App Deployment Manifests (optional)​

OPTIONAL STEP
  • This step allows you to preview the Kubernetes manifests that Wayfinder will generate for your application.
  • Note that you will not be deploying anything to the cluster in this section.

To preview the app deployment manifests:

  • Specify which existing environment (cluster) will host your application.
  • Use the dry-run flag to instruct Wayfinder to generate the manifests so that you can preview them.

Step 3.1 Create an environment using existing infrastructure​

The wf deploy application command requires an environment (existing cluster) as input, so you need to create one if you haven't already done so.

Wayfinder Create an Environment
wf create appenv --app app1 --env demo1 --cluster aks-2eqk9 --stage nonprod


For More Information See

Step 3.2 Use the dry-run flag to instruct Wayfinder to generate the manifests so that you can preview them​

note

When using the dry-run flag, you suppress any deployment actions to the cluster.

Wayfinder Generate App Deployment Manifests 
wf deploy application app1 demo1 -w sand2 --dry-run -o yaml
For More Information See


Step 4: Create a Workspace Access Token and give it access permissions​

You need a Workspace Access Token to automate your app deployments in your CI system. This involves you creating the token and then giving it permissions to access your cluster(s) / application environment(s).

Create the Workspace Access Token

Wayfinder Create a Workspace Access Token
wf create workspaceaccesstoken wf-app1deploy

Permission the Workspace Access Token

Permission the token with cluster/namespace access role permissions.

Wayfinder assign access roles to a Workspace Access Token
wf assign accessrole --workspace-access-token wf-app1deploy --role cluster.deployment-readonly  --cluster aks-2eqk9
wf assign accessrole --workspace-access-token wf-app1deploy --role cluster.deployment  --cluster aks-2eqk9
wf assign accessrole --workspace-access-token wf-app1deploy --role namespace.deployment --cluster aks-2eqk9 --namespace app1-demo1

Permission the token with Wayfinder role access permissions.

Wayfinder assign access roles to a Workspace Access Token
wf assign wayfinderrole --workspace-access-token wf-app1deploy --role workspace.appdeployer 
wf assign wayfinderrole --workspace-access-token wf-app1deploy --role workspace.appmanager

For More Information See


Step 5: Set GitHub secrets​

External Action

The configuration described here takes place outside of Wayfinder.


After creating your Workspace Access Token, you need to add the WAYFINDER_TOKEN value as a secret in a GitHub variable. This step enables its usage by the GitHub PR workflow.

Use GitHub's CLI command for this step: gh secret set

gh secret set WAYFINDER_TOKEN -R appvia/wf-example-app -a actions
For More Information See


Step 6: Set GitHub variables​

External Action

The configuration described here takes place outside of Wayfinder.


You also need to set the gitHub variables outlined below in GitHub. Remember to adjust the variable values as needed for your application.

gh variable set WAYFINDER_WORKSPACE -r appvia/wf-example-app --body ws1
gh variable set WAYFINDER_SERVER -r appvia/wf-example-app --body https://api-wayfinder.myorg.io
gh variable set APP_NAME -r appvia/wf-example-app --body wfexampleapp
gh variable set APP_COMPONENT_NAME -r appvia/wf-example-app --body ui
gh variable set PR_PREVIEW_CLUSTER -r appvia/wf-example-app --body demo-envs
gh variable set LIVE_ENV_NAME -r appvia/wf-example-app --body prod
For More Information See


Step 7: Configure GitHub Workflow for Deployment to an Ephemeral PR Preview Environment​

External Action

The configuration described here takes place outside of Wayfinder.


In this section you're configuring the .github/workflows/pr.yaml file so when you commit your deployment manifests for the first time, then it will deploy your application to an ephemeral PR Preview environment and generate a PR preview link. On subsequent commits, it will redeploy your app component.

name: build-publish

on:
  pull_request:

  build:
    runs-on: ubuntu-latest
    outputs:
      tags: ${{ steps.meta.outputs.tags }}
    - name: Login to docker registry
      uses: docker/login-action@v1
      with:
        registry: ghcr.io
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
    - name: Build and Push to GitHub Packages
      id: build-push
      uses: docker/build-push-action@v2
      continue-on-error: true
      timeout-minutes: 3
      with:
        context: .
        file: ./Dockerfile
        push: true
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}

  deploy-pr-preview:
    needs:
    - build
    runs-on: ubuntu-latest
    container:
      image: quay.io/appvia-wf-dev/wftoolbox:latest
    steps:
      - name: Deploy to app environment
        id: deploy
        env:
          WAYFINDER_SERVER: ${{ vars.WAYFINDER_SERVER }}
          WAYFINDER_WORKSPACE: ${{ vars.WAYFINDER_WORKSPACE }}
          WAYFINDER_TOKEN: ${{ secrets.WAYFINDER_TOKEN }}
          IMAGE_TAG: ${{ needs.build.outputs.tags }}
        run: |
          export ENV_NAME="pr-${{ github.event.pull_request.number }}"
          wf create appenv --app MY_APP_NAME --env ${ENV_NAME} --cluster ${{ vars.PR_PREVIEW_CLUSTER }} --stage nonprod || true
          wf deploy component MY_APP_NAME ${ENV_NAME} --component MY_COMPONENT_NAME --image ${IMAGE_TAG} --wait-for-ready 3m
For More Information See

Step 8: Configure GitHub Workflow for Ephemaral PR Preview Teardown on Merge​

External Action

The configuration described here takes place outside of Wayfinder.


In this section you're configuring the .github/workflows/pr-closed.yaml file so that it deletes your ephemeral PR Preview environment when you close your PR.

name: pr-preview-teardown

on:
  pull_request:
    types: [closed]

jobs:
  teardown-preview:
    runs-on: ubuntu-latest
    container:
      image: quay.io/appvia-wayfinder/wftoolbox:latest
    steps:
      - name: Clean up old resources
        env:
          WAYFINDER_SERVER: ${{ vars.WAYFINDER_SERVER }}
          WAYFINDER_WORKSPACE: ${{ vars.WAYFINDER_WORKSPACE }}
          WAYFINDER_TOKEN: ${{ secrets.WAYFINDER_TOKEN }}
        run: |
          export ENV_NAME="pr-${{ github.event.pull_request.number }}"
          wf delete appenv ${{ vars.APP_NAME }}-${ENV_NAME} || true
For More Information See

Step 9: Configure GitHub Workflow for Deploying to a Long-Lived Environment on Merge​

External Action

The configuration described here takes place outside of Wayfinder.


In this section you're configuring the .github/workflows/main.yaml file so that it deploys your component to your long-lived PROD environment.

name: main-publish

on:
  push:
    branches: [main]

permissions:
  contents: read # Required for actions/checkout
  checks: write # Set status of checks
  issues: write # Comment the PR as we go
  statuses: write # Set commit statuses as tests pass or fail
  pull-requests: write # Get/comment the PR itself
  packages: write # Write to ghcr.io

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      tags: ${{ steps.meta.outputs.tags }}
    steps:
    - name: Login to docker registry
      uses: docker/login-action@v3
      with:
        registry: ghcr.io
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
    - name: Docker metadata
      id: meta
      uses: docker/metadata-action@v5
      with:
        images: ghcr.io/${{ github.repository }}/wfexample
        tags: |
          type=ref,event=branch,suffix=-{{sha}}
          type=ref,event=pr,suffix=-{{sha}}
    - name: Build and Push to GitHub Packages
      id: build-push
      uses: docker/build-push-action@v5
      with:
        push: true
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}

  deploy-live:
    needs:
    - build
    runs-on: ubuntu-latest
    container:
      image: quay.io/appvia-wayfinder/wftoolbox:latest
    steps:
      - name: Deploy to app environment
        id: deploy
        env:
          WAYFINDER_SERVER: ${{ vars.WAYFINDER_SERVER }}
          WAYFINDER_WORKSPACE: ${{ vars.WAYFINDER_WORKSPACE }}
          WAYFINDER_TOKEN: ${{ secrets.WAYFINDER_TOKEN }}
        run: |
          wf deploy component ${{ vars.APP_NAME }} ${{ vars.LIVE_ENV_NAME }}  --component ${{ vars.APP_COMPONENT_NAME }} --image ${{ needs.build.outputs.tags }} --wait-for-ready 3m
For More Information See