JFrog x HashiCorp demo repository

This example repository showcases simple CI/CD workflows to automate containerized application deployment to HashiCorp Nomad cluster with GitOps model, using JFrog Artifactory and its docker image promotion feature.

Workflow overview

1. A Pull Request is opened with some modifications to the codebase.
2. GitHub Actions workflow (pull_request.yml) is trrigered, then start building a Docker image from source, testing, and performs a container scanning using JFrog Xray.
3. If all jobs above are passed, push the built image to JFrog Artifactory (to the staging repo).
4. Deploy a staging Nomad job that is specific to the triggered PR branch, and create a disposable preview environment.
5. Devs can access this preview environment for QA (multiple previews can run at the same time with branch-specific URLs)
6. Once the PR has merged, the preview environment (Nomad job) is stopped and purged by the GitHub Actions workflow (cleanup-jobs.yml), and another GitHub Actions workflow (promote-to-rc.yml) will promote the Docker image that was built in this PR from staging to “Release candidate (RC)” repository.
7. These processes above will repeat for any PRs and ensure we always have a ready image pushed in the RC repository.
8. Finally, when a new Git tag is pushed, GitHub Actions workflow (deploy-production.yml) will promote the latest RC image to production, and re-deploy production Nomad jobs to use this new image.

Setup

Prerequisites

• You have a valid JFrog SaaS account (A free trial acount should be sufficient).
• You have a ngrok account and can run it on your local machine.
• You have a Docker Engine (e.g., Docker Desktop) installed on your local machine.

Nomad

1. Run Nomad on your local machine (dev mode)

Download the Nomad binary that works for your platform and run the following command:

NOTE: Requires Nomad version 1.3+ since this demo uses the native service discovery feature added in 1.3.

nomad agent -dev -acl-enabled -bind=0.0.0.0

This will start the Nomad process in dev mode with ACL enabled. Please keep this terminal active and use a separate terminal session for subsequent steps/commands.

2. bootstrap Nomad ACL token

nomad acl bootstrap

It will print some bootstrap information containing the ACL token. Then, take a memo of the Secret ID value.

3. Deploy Nginx job

First, set NOMAD_TOKEN environment variable with the value from the step 2 above.

export NOMAD_TOKEN="your_nomad_acl_token"

Then, deploy the Nginx job.

nomad job run nomad/jobs/nginx.nomad

Check the status of the job:

nomad job status nginx

4. Activate Nomad UI (optional)

If you also want to access Nomad UI for better visibility, go check out http://127.0.0.1:4646/ui and authenticate with the ACL token we got in the previous steps.

5. Run ngrok

Since your Nomad cluster is running on your local machine, we need to expose our cluster to the internet so that GitHub Actions can access and make API requests to your Nomad cluster.

ngrok makes it easy and also provides a secure connection (https) for free.

ngrok http 4646

This command will start a new ngrok session and print a one-time unique URL that is proxied to your local Nomad process listening on port 4646. Please take a memo of the Forwarding (https) URL.

Also, please keep this terminal active and use a separate terminal session for subsequent steps/commands.

JFrog

Create API key

To access JFrog services via API, you need to generate your API key. Please refer to JFrog's official documentation for how to get one, and take a memo of the generated API key.

Create local repositories

In this example, you need to have three local repositoreis (type: Docker) to set up the image promotion workflows.

Stage	Repository Name (any)
Staging	e.g., jfrog-hashicorp-demo-staging
Release candidate	e.g., jfrog-hashicorp-demo-rc
Production	e.g., jfrog-hashicorp-demo-production

GitHub Secrets

The workflows in this repo require some secrets pre-defined in GitHub Secrets (repository secrets are preferred this time).

Name	Value
JFROG_USER_NAME	your JFrog account user name
JFROG_API_KEY	your JFrog account API key
NOMAD_ADDR	your Nomad cluster address (i.e., the URL provided by ngrok above)
NOMAD_TOKEN	your Nomad ACL token (generated by the bootstrap command above)

RECOMMENDED: You can also use HashiCorp Vault for better secret management and migrate all GitHub Secrets into Vault. With GitHub Actions OIDC support, you can securely retrieve secrets from remote Vault "on-demand" during job execution. Check out our official Vault actions for more details.

Environment Variables

The workflows reference actions.env file during job execution. This is to export pre-defined environment variables to job steps.

Please update actions.env file with your system information accordingly.

NOTE: This file should not contain any sensitive information.

Name	Value
DOCKER_IMAGE_NAME	your desired Docker image name (e.g., smaeda-ks/jfrog-hashicorp-demo)
JFROG_URL	your JFrog instance URL (e.g., yourdemoaccount.jfrog.io)
JFROG_REPO_STAGING	e.g., jfrog-hashicorp-demo-staging
JFROG_REPO_RC	e.g., jfrog-hashicorp-demo-rc
JFROG_REPO_PRODUCTION	e.g., jfrog-hashicorp-demo-production