Source Control with VGS

Using a Source Control tool such as git provides you with a change control system allowing you to programmatically apply and compare changes and perform versioning without needing humans to manually apply changes. This is useful when you must apply changes in accordance with a specific Software Development Lifecycle (SDLC) for security or compliance purposes.

By the end of this tutorial you will be able to utilize version control for route configurations using git.

We also have a fully working git flow example using Github Actions.

Prerequisites

  1. VGS CLI service account

  2. VGS Dashboard account

  3. Github account

Overview

In this guide, we cover:

  • How to install and set up the vgs-cli

  • How to download your VGS Vault's routes and test them locally

  • How to integrate your VGS Routes changes into your git workflow.

Install VGS CLI

The VGS CLI is a developer tool that helps you build, test, and manage your configurations in VGS programmatically. It enables the usage of VGS APIs in code or as a part of CI/CD pipelines.

PyPI

This option requires Python 3 to be installed. To install the latest VGS CLI from PyPI:

pip install vgs-cli

Verify your installation by running:

vgs --version

1. Provision a Service Account

After installing the CLI, you must log in with your VGS account to authenticate the CLI in order to generate a service account programmatically. This is a one time step.

vgs login

To create a service account for your organization do the following:

  1. Generate the service account configuration from a template and store it to the service_account.yaml file

vgs generate service-account -t vgs-cli > service_account.yaml

If needed, change the name and add/remove scopes according to your needs by editing the service_account.yaml file. You can learn more about scopes and resources) to manage permissions.

2. Apply the service account configuration

You can find your organization ID in the VGS dashboard

vgs apply service-account -O <ORGANIZATION_ID> -f service_account.yaml

As a result of the above-mentioned steps, you will have an output that will look similar to:

apiVersion: 1.0.0
kind: ServiceAccount
data:
    clientId: ACxxxxxxx-vgs-cli-xxxxx
    clientSecret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx
    name: vgs-cli
    scopes:
      - access-logs:read
      - routes:write
      - vaults:read

Now, with clientId and clientSecret, you can set up Authentication and test the VGS CLI.

Environment

echo export VGS_CLIENT_ID=ACxxxxxxx-vgs-cli-xxxxx >> ~/.bashrc
echo export VGS_CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx >> ~/.bashrc

or

echo export VGS_CLIENT_ID=ACxxxxxxx-vgs-cli-xxxxx >> ~/.zshrc
echo export VGS_CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx >> ~/.zshrc

use source ~/.bashrc or source ~/.zshrc respectively

Working with routes

Now we can store our current vault's route config in a file by piping the output from the CLI

vgs get routes --vault <VAULT_ID> > routes.yaml

Now, create a git repository to store YAML files of your routes:

git init
git add routes.yaml
git commit -m "Initial commit"
git branch -M master
git remote add origin [email protected]:jsmth/my-routes.git
git push -u origin master

Making changes to routes

Now, let's say that we want to change the format of our credit card number alias format to use a Format Preserving, Luhn Valid (6T4) representation so that BIN and the last four digits are preserved (e.g. 4111111111111111 becomes something like 4111119381251111).

In order to accomplish this, we need to:

  1. Apply changes to our local routes file

  2. Save changes to git

  3. Apply updated routes to our vault

  4. Check the vault's logs to see if everything is working correctly

Let's start by updating the routes. We need to find the portions where card_number is being redacted and revealed in inbound and outbound routes, and changes the public_token_generator in both those locations from UUID to FPE_SIX_T_FOUR. You can check out all of the available VGS aliasing formats on our docs.

git diff
diff --git a/vgs_routes.yaml b/vgs_routes.yaml
index b922a01..e8b089d 100644
--- a/vgs_routes.yaml
+++ b/vgs_routes.yaml
@@ -29,7 +29,7 @@ data:
       operation: REDACT
       operations: null
       phase: REQUEST
-      public_token_generator: UUID
+      public_token_generator: FPE_SIX_T_FOUR
       targets:
       - body
       token_manager: PERSISTENT
@@ -79,7 +79,7 @@ data:
       operation: ENRICH
       operations: null
       phase: REQUEST
-      public_token_generator: UUID
+      public_token_generator: FPE_SIX_T_FOUR
       targets:
       - body
       token_manager: PERSISTENT

Apply changes to your git repo

git add vgs_routes.yaml
git commit -m "Changed UUID format to FPE_SIX_T_FOUR"
git push -u origin master

Apply changes to your Vault

To apply the newly created routes to our vault, make sure that the VGS CLI is running and authenticated. Then, use the vgs apply command:

vgs apply routes --vault <VAULT_ID> -f routes.yaml
Route 4a74170c-2638-45c8-8880-1ea3cf66f38a processed
Route 6d2135c7-f20b-46ba-bee6-e58159c42e6d processed
Routes updated successfully for vault tntfpb2sssw

Verify Applied Changes

You can validate that the changes were applied by fetching your Vaults route configuration again and comparing

vgs get routes --vault <VAULT_ID> > routes.yaml
git diff

Congratulations, you've mastered the basics of using git to control your VGS Vault configuration.

Next steps

PreviousOverviewNextVGS Collect

Last updated