Encrypting Cluster Config Files

This documentation is provided in DRAFT form.

Your cluster configuration files store cluster information in plain text, including required credentials and SSL certs in some files. Apcera recommends that you secure and version control these files, including cluster.conf, cluster.conf.erb, main.tf, and terraform.tfvars. To do this we recommend that you create a Git repository for your cluster installation files and encrypt the sensitive ones.

You can encrypt your cluster configuration files and allow for secure collaboration using git-crypt. You can use gpg-agent forwarding to remotely decrypt the file and deploy the cluster.

Although git-crypt supports the use symmetric keys, Apcera does not recommend this approach because it requires a key to exist on the Orchestrator host to decrypt the cluster.conf file. The best practice is to use gpg-agent forwarding as described here.

Create GPG keys for Cluster Admins

The primary cluster administrator should create a GPG key for use with git-crypt for each user who will be updating cluster.conf and deploying the cluster, including herself. This lets you manage cluster admins by adding or removing the necessary GPG keys.

  1. Install GPG.

    On Mac you can run brew install gpg.

    Or you can download the binary for your OS here (at the bottom of the page).

  2. Verify installation.

     $ gpg --version
  3. Use GPG to generate a key pair.

     $ gpg --gen-key
  4. Configure the key.

    a. Press Enter to accept the default RSA and RSA.
    b. Enter 4096 for the key size (the maximum key size is recommended).
    c. Enter the key expiration date (the default never is not recommended).

  5. Enter the user ID information.

    a. Real name
    b. Email address
    c. Comment

    The user ID takes the form real name (comment) <email@address.com> and can be used to authorize git-crypt collaborators as described above.

  6. Enter a passphrase to protect the secret key.

  7. Verify gpg key creation.

     gpg --list-keys
     pub   2048R/65A9AEDD 2016-12-22
     uid                  john bombalone (yeeha) <bombalone@acme.com>
     sub   2048R/4E76BA7F 2016-12-22

Create an encrypted git repo

Apcera recommends that you create an encrypted git repo for securing and versioning your cluster installation files. The repo is not encrypted until you set up git-crypt as described below. Because the cluster.conf file contains secrets, you should not generate it until you have set up git-crypt.

  1. Install git.

     brew install git
  2. Verify git installation.

     git version
     git version 2.2.0
  3. Create a new git repo for your Apcera installation.

    In this example we call it my-apcera-repo.

  4. Install git-crypt.

     brew install git-crypt
  5. Verify git-crypt installation.

     git-crypt version
     git-crypt 0.5.0
  6. Configure the repo to use git-crypt.

     cd my-apcera-repo
     git-crypt init
     Generating key...

    This command generates an encryption key and places it in the /repo/.git-crypt/keys/default directory.

  7. Create a plain text file named .gitattributes in the root folder of the repo.

  8. Edit .gitattributes and specify the files to be encrypted.

     *.conf filter=git-crypt diff=git-crypt
     *.conf.erb filter=git-crypt diff=git-crypt
     main.tf filter=git-crypt diff=git-crypt
     terraform.tfvars filter=git-crypt diff=git-crypt    // If using the AWS Terraform module

    You may want to encrypt other files, or encrypt all files in a directory, such as in a folder named /repo/secrets.

     secrets/** filter=git-crypt diff=git-crypt

    Be careful not encrypt the .gitattributes file, however.

  9. Share the repository with others (or with yourself) using GPG:

     git-crypt add-gpg-user USER_ID

    Where USER_ID is the full user ID of the GPG key for each cluster admin.

    For example:

     git-crypt add-gpg-user "REAL NAME (comment) <email@address.com>"
     [master 86c6241] Add 1 git-crypt collaborator
      2 files changed, 3 insertions(+)
      create mode 100644 .git-crypt/.gitattributes
      create mode 100644 .git-crypt/keys/default/0/494657966BA2400847BBF3F6F873DF2E65A9AEDD.gpg
  10. Commit the repo changes and merge them to master.

    You must commit the repo changes before you add files to be encrypted, otherwise they will not be encrypted and you receive the following message:

    Warning: one or more files is marked for encryption via .gitattributes but was staged and/or committed before the .gitattributes file was in effect. 

    If this occurs you can run git-crypt status with the -f option to stage an encrypted version.

  11. Test git-crypt repo encryption.

    Apcera recommends that you test git-crypt encryption before proceeding.

    Simply create a branch for your repo, then create a file with some text in it named test-git-crypt.conf. Verify that this file is encrypted.

Download the Apcera installation files

Now that you have set up the encrypted repo you can generate the cluster.conf file.

  1. Download the installation ZIP file from Apcera Support for your deployment platform, including the Terraform module(s), example files, and cluster.conf.erb file.

  2. Create a git branch for your repo.

     git checkout -b my-initial-deploy
  3. Extract the installation files to the git repo.

  4. Generate the initial (unpopulated) cluster.conf file as described in the documentation for your installation type.

     erb cluster.conf.erb > cluster.conf
  5. Commit the changes and verify encryption.

    Confirm that the cluster.conf and cluster.conf.erb files are encryted (and any others as appropriate, such as main.tf.)

Deploy the cluster

  1. Sync (pull) the git repo so you have the latest changes.

  2. Generate the populated cluster.conf file as described in the documentation for your installation type.

  3. Commit the changes.

  4. SCP the encrypted cluster.conf file to the Orchestrator machine.

  5. Configure gpg-agent forwarding.

    Forward the public GPG key to the Orchestrator host. With this approach, the GPG keys of the unlocker are never on the Orchestrator box, as git-crypt supports gpg-agent forwarding. They keys stay on the local admin's machine.

    Refer to these instructions to configure gpg-agent forwarding.

  6. Remotely decrypt the using git-crypt unlock.

  7. Once the deploy is complete, run git-crypt lock to encrypt the file.