Getting started

Install

sh -c "$(curl --location https://raw.githubusercontent.com/PierreBeucher/novops/main/install.sh)"

See installation for more installation methods.

Usage

Consider a typical workflow: run build and deployment with secrets from Hashicorp Vault and temporary AWS credentials.

Create .novops.yml and commit it safely - it does not contain any secret:

environments:
  dev:
    
    # Environment variables for dev environment
    variables:
      
      # Fetch Hashicorp Vault secrets
      - name: DATABASE_PASSWORD
        value:
          hvault_kv2:
            path: crafteo/app/dev
            key: db_password
       
      # Plain string are also supported
      - name: DATABASE_USER
        value: root
    
    # Generate temporary AWS credentials for IAM Role
    # Provide environment variables:
    # - AWS_ACCESS_KEY_ID
    # - AWS_SECRET_ACCESS_KEY
    # - AWS_SESSION_TOKEN
    aws:
      assume_role:
        role_arn: arn:aws:iam::12345678910:role/dev_deploy

Load secrets as environment variables:

# Source directly into your shell
source <(novops load)

# Or run sub-process directly
novops run -- make deploy

Secrets are now available:

echo $DATABASE_PASSWORD
# passxxxxxxx

env | grep AWS
# AWS_ACCESS_KEY_ID=AKIAXXX
# AWS_SECRET_ACCESS_KEY=xxx
# AWS_SESSION_TOKEN=xxx

🔐 Security

Secrets are loaded temporarily as environment variables or in a protected tmpfs directory and kept only for as long as they are needed. See Novops Security Model for details

Run Novops with...

Shell

Either source directly into your shell or run a sub-process:

# bash / ksh: source with process substitution
source <(novops load)

# zsh: source with process substitution
source =(novops load)

# Run sub-process directly
novops run -- some_command

# load in .env file (novops creates a symlink pointing to secure temporary file)
novops load -s .envrc && source .envrc

🐳 Docker & Podman

Load environment variables directly into containers:

docker run -it --env-file <(novops load -f dotenv -e dev) alpine sh

podman run -it --env-file <(novops load -f dotenv -e dev) alpine sh

More examples

Load and generate temporary secrets

Novops load and generate temporary secrets from various platforms and providers as configured in .novops.yml.

Hashicorp Vault

Multiple Hashicorp Vault Secret Engines are supported:

  • Key Value v1/v2
  • AWS to generate temporary credentials
environments:
  dev:
    variables:
      
      # Key Value v2
      - name: DATABASE_PASSWORD
        value:
          hvault_kv2:
            path: crafteo/app/dev
            key: db_password
      
      # Key Value v1
      - name: SECRET_TOKEN
        value:
          hvault_kv1:
            path: crafteo/app/dev
            key: token
            mount: kv1

    # Hashivault module with AWS secret engine
    # Generate environment variables:
    # - AWS_ACCESS_KEY_ID
    # - AWS_SECRET_ACCESS_KEY
    # - AWS_SESSION_TOKEN
    hashivault:
      aws:
        name: dev_role
        role_arn: arn:aws:iam::111122223333:role/dev_role
        role_session_name: dev-session
        ttl: 2h

See Hashicorp Vault doc

AWS

Multiple AWS services are supported:

  • Secrets Manager
  • STS Assume Role for temporary IAM Role credentials
  • SSM Parameter Store
environments:
  dev:

    variables:
      # SSM Parameter Store
      - name: SOME_PARAMETER_STORE_SECRET
        value:
          aws_ssm_parameter:
            name: secret-parameter
      
      # Secrets Manager
      - name: SOME_SECRET_MANAGER_PASSWORD
        value:
          aws_secret:
            id: secret-password
    
    # Generate temporary AWS credentials for IAM Role
    # Generate environment variables:
    # - AWS_ACCESS_KEY_ID
    # - AWS_SECRET_ACCESS_KEY
    # - AWS_SESSION_TOKEN
    aws:
      assume_role:
        role_arn: arn:aws:iam::12345678910:role/dev_deploy

See AWS doc

More examples

Multi-environment context

.novops.yml can be configure with multiple environments:

environments:
  dev:
    variables:      
      - name: DATABASE_PASSWORD
        value:
          hvault_kv2:
            path: crafteo/app/dev
            key: db_password
  prod:
    variables:      
      - name: DATABASE_PASSWORD
        value:
          hvault_kv2:
            path: crafteo/app/prod
            key: db_password

Novops will prompt for environment by default

novops load 
# Select environment: dev, prod

You can also specify environment on command line

novops load -e dev

Or specify a default environment in .novops.yml

config:
  default:
    environment: dev

Files

Novops can also write files such as SSH keys. Files are kept in a tmpfs secured directory, see Novops Security Model.

environments:
  dev:   
    files:
      
      # Each file entry generates a file AND an environment variable
      # pointing to generated file such as
      # ANSIBLE_PRIVATE_KEY=/run/user/1000/novops/.../file_ANSIBLE_PRIVATE_KEY
      - variable: ANSIBLE_PRIVATE_KEY
        content:
          hvault_kv2:
            path: crafteo/app/dev
            key: ssh_key

See Variables and Files doc

Plain strings

Variables and files can also be loaded as plain strings. This can be useful to specify both user and passwords or some generic configs.

environments:
  dev:
    variables:      
      # Plain string will be loaded as DATABASE_USER="app-dev"
      - name: DATABASE_USER
        value: app-dev

      - name: DATABASE_PASSWORD
        value:
          hvault_kv2:
            path: crafteo/app/dev
            key: db_password
    files:
      # File with plain string content
      - variable: APP_CONFIG
        content: |
            db_host: localhost
            db_port: 3306

Next steps