Getting Started

Tutorial¶

For full Keyper tutorial, you can find it here: https://github.com/jarrid-xyz/keyper-tutorial

Keyper Github Action¶

We've created the Keyper Github Action to automate Keyper deployment using GitOps flow. This makes Keyper resource management fully configuration-driven. Both technical and non-technical teams can either edit the configuration files directly or use the Keyper CLI to manage resources and the Keyper Github Action will handle the rest of the CI/CD process.

➡️ Go to Keyper Github Action Tutorial.

The easiest way to set it up is to copy our example workflow into your own repository and modify the configurations accordingly:

name: Keyper Action (Deploy Plan/Apply)

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  keyper-action:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Keyper Action (Deploy Plan)
        id: keyper-plan
        uses: jarrid-xyz/keyper@v0.0.4
        with:
          args: deploy plan
      - name: Run Keyper Action (Deploy Apply)
        id: keyper-apply
        uses: jarrid-xyz/keyper@v0.0.4
        with:
          args: deploy apply
        if: github.ref == 'refs/heads/main' # Only run if merge to main

Keyper Docker CLI¶

Pull Docker Image¶

Pull Keyper's pre-packaged docker images: ghcr.io/jarrid-xyz/keyper:v0.0.4

docker pull ghcr.io/jarrid-xyz/keyper:v0.0.4

Create App Configuration and Credentials¶

Follow Keyper Configuration to create app.<env>.yaml to configure Terraform provider and backend accordingly.
Follow Create GCP KMS Admin Service Account to create .cdktf-sa-key.json. This service account credential is needed to create actual resources via Terraform.

Run Keyper Command¶

Validate that docker image is working properly.

docker run -it --rm --name keyper-cli \
    -v ./configs:/home/keyper/configs \
    -v ./cdktf.out:/home/keyper/cdktf.out \
    -v ./.cdktf-sa-key.json:/home/keyper/gcp.json \
    -v ./app.local.yaml:/home/keyper/app.local.yaml \
    ghcr.io/jarrid-xyz/keyper:v0.0.4 -h

Create Deployment, Role and Key¶

Create the resource configurations locally.

docker run -it --rm --name keyper-cli \
    -v ./configs:/home/keyper/configs \
    -v ./cdktf.out:/home/keyper/cdktf.out \
    -v ./.cdktf-sa-key.json:/home/keyper/gcp.json \
    -v ./app.local.yaml:/home/keyper/app.local.yaml \
    ghcr.io/jarrid-xyz/keyper:v0.0.4 resource create -t deployment

docker run -it --rm --name keyper-cli \
    -v ./configs:/home/keyper/configs \
    -v ./cdktf.out:/home/keyper/cdktf.out \
    -v ./.cdktf-sa-key.json:/home/keyper/gcp.json \
    -v ./app.local.yaml:/home/keyper/app.local.yaml \
    ghcr.io/jarrid-xyz/keyper:v0.0.4 resource create -t role -n app-role

docker run -it --rm --name keyper-cli \
    -v ./configs:/home/keyper/configs \
    -v ./cdktf.out:/home/keyper/cdktf.out \
    -v ./.cdktf-sa-key.json:/home/keyper/gcp.json \
    -v ./app.local.yaml:/home/keyper/app.local.yaml \
    ghcr.io/jarrid-xyz/keyper:v0.0.4 resource create -t key

Deploy via Terraform¶

Provision resource on the cloud based on the resource configurations.

docker run -it --rm --name keyper-cli \
    -v ./configs:/home/keyper/configs \
    -v ./cdktf.out:/home/keyper/cdktf.out \
    -v ./.cdktf-sa-key.json:/home/keyper/gcp.json \
    -v ./app.local.yaml:/home/keyper/app.local.yaml \
    ghcr.io/jarrid-xyz/keyper:v0.0.4 deploy apply

Encrypt/Decrypt Data with Key¶

docker run -it --rm --name keyper-cli \
    -v ./configs:/home/keyper/configs \
    -v ./cdktf.out:/home/keyper/cdktf.out \
    -v ./.cdktf-sa-key.json:/home/keyper/gcp.json \
    -v ./app.local.yaml:/home/keyper/app.local.yaml \
    ghcr.io/jarrid-xyz/keyper:v0.0.4 data encrypt -k <key-id> --plaintext <secret>

docker run -it --rm --name keyper-cli \
    -v ./configs:/home/keyper/configs \
    -v ./cdktf.out:/home/keyper/cdktf.out \
    -v ./.cdktf-sa-key.json:/home/keyper/gcp.json \
    -v ./app.local.yaml:/home/keyper/app.local.yaml \
    ghcr.io/jarrid-xyz/keyper:v0.0.4 data decrypt -k <key-id> --ciphertext <secret>

You just successfully use KMS key to encrypt/decrypt data.