Setup

The easiest way to run configrd

Docker images are hosted on Configrd’s Docker Hub.

Running docker as a container requires the following steps:

  1. Pull latest docker image from docker hub
  2. Tell the service where to find the configrd.yaml file with repository definitions
  3. Optionally override basic service parameters such as port and log level

Pull configrd-service

Pull the configrd-service image from docker hub with the latest features

    
docker pull configrd/configrd-service

  

Start configrd-service

The most basic way to start the service is by allowing configrd to read/write a default configrd.yaml configuration file to the local file system by binding the container’s path /srv/configrd to a local volume mount. By default, the service listens on port 9191.

    
docker run -d -p 9191:9191 -v /srv/configrd:/srv/configrd configrd/configrd-service

  

You can map the local volume to any location on disk desirable but the path from within the container should remain beginning with /srv/configrd.

    
docker run -d -p 9191:9191 -v /home/myuser/configrd:/srv/configrd configrd/configrd-service

  

Checking the docker logs for the container you should see output similar to the below

    
00:04:38.462 [main] INFO  io... - Configrd starting on port 9191
00:04:38.480 [main] INFO  io... - Starting configrd...
00:04:38.709 [main] INFO  io... - Attempting to load configrd config file from file:/srv/configrd/configrd.yaml using source file
00:04:38.738 [main] INFO  io... - Loaded configrd config file at file:/srv/configrd/configrd.yaml
00:04:38.977 [main] INFO  io... - Application deployed
00:04:38.977 [main] INFO  io... - Configrd started in 0s

  

Loading configrd.yaml

There are several sources available for loading the configrd.yaml file on container start and all options are passed as ENV parameters to the container on docker run. Some ENV parameters options are source specific.

File System

Loading the configrd.yaml file from a local or locally mounted file system is the default approach supported.

ENVRequiredDefaultDescription
SOURCENAMEYesfileUse the “file” source to load the configrd.yaml from the file system
CONFIG_URIYesfile:/srv/configrd/configrd.yamlAbsolute path to the configrd.yaml file on the file system. Must start with “file:/srv/configrd/…”

To load the configrd service configuration from a file named different than configrd.yaml, simply specify the file name in the CONFIG_URI ENV parameter.

    
docker run -d -p 9191:9191 -e SOURCENAME=file -e CONFIG_URI=file:/srv/configrd/myconfig.yaml -v /home/myuser/configrd:/srv/configrd configrd/configrd-service

  

HTTP/S

The configrd.yaml file can be loaded over http/s including endpoints protected by HTTP Basic Authentication with self signed certificates.

ENVRequiredDefaultDescription
SOURCENAMEYesUse the “http” source to load configrd.yaml from a http/s location
CONFIG_URIYesAbsolute path to the configrd.yaml file over http/s. Must start with http:// or https://.
TRUSTCERTNofalseFlag to trust the TLS certificate of the http/s source
USERNoUsername used for the authorization header with Basic Auth
SECRETNoPassword used for the authorization header with Basic Auth
    
docker run -d -p 9191:9191 -e SOURCENAME=http -e CONFIG_URI=https://myservice.com/configrd/configrd.yaml configrd/configrd-service

  

AWS S3

AWS S3 block storage is supported as a source. Assuming you are not using a public s3 bucket, configrd can authenticate using static AWS credentials if connecting to an S3 bucket from outside of AWS.

Configrd instances deployed to AWS services such as EC2, ECS, EKS, LightSail or Elastic Beanstalk can take advantage of the AWS environment’s security context.

ENVRequiredDefaultDescription
SOURCENAMEYesUse the “s3” source to load configrd.yaml from an s3 bucket
CONFIG_URIYesAbsolute path to the configrd.yaml file in s3. Only the http/s transport protocol is supported. No s3://.
AWS_ACCESS_KEY_IDNoStatic AWS credentials to authenticate against s3 bucket. Not required when running from within AWS using roles or security groups
AWS_SECRET_ACCESS_KEYNoStatic AWS credentials to authenticate against s3 bucket. Not required when running from within AWS using roles or security groups
    
docker run -d -p 9191:9191 -e SOURCENAME=s3 -e CONFIG_URI=https://s3.amazonaws.com/mybucket/configrd.yaml configrd/configrd-service

  

Git, GitHub, AWS CodeCommit

Configrd has been tested with several git repository providers for sourcing the configrd.yaml file from a versioned repository.

The service supports the most populate authentication methods including static credentials, temporary tokens, ssh private keys and static AWS credentials as well as static AWS git credentials.

The git repository will be cloned into /srv/configrd/init on the container at startup and the configrd.yaml loaded from the local file system. The git repository is only pulled at service start. If you do not bind the /srv/configrd container path to a volume mount the files will only live inside the container.

AWS roles are not yet supported as an authentication mechanism. AWS does not recommend using IAM credentials or the EC2 security context for CodeCommit authentication since credentials expire.

ENVRequiredDefaultDescription
SOURCENAMEYesUse the “git” source to load configrd.yaml from a git repository
CONFIG_URIYesAbsolute path to the git repository where the configrd.yaml file exists at the root. Ssh, git and https are all supported protocols.
AUTH_METHODYesOne of CodeCommitGitCreds, CodeCommitIAMUser, GitHub, GitHubToken, SshPubKey
CONFIG_FILENoconfigrd.yamlName of configrd.yaml file in git repo at root
USERNoUsername, AWS static or AWS git access key
SECRETNoPassword, AWS static or AWS git secret
TOKENNoGitHub token authentication
PKNoAbsolute path to ssh private key for GitHub ssh or AWS private key authentication

Sample docker run with GitHub username and secret

    
docker run -d -p 9191:9191 -e AUTH_METHOD=GitHub -e SOURCENAME=git -e CONFIG_URI=git@github.com:myorg/myrepo.git -e USER=$GITHUB_USER -e SECRET=$GITHUB_SECRET configrd/configrd-service

  

Sample docker run with GitHub SSH public key authentication

    
docker run -d -p 9191:9191 -e AUTH_METHOD=SshPubKey -e PK=~/.ssh/rsa_id -e SOURCENAME=git -e CONFIG_URI=git@github.com:myorg/myrepo.git configrd/configrd-service

  

Sample docker run with GtiHub token authentication

    
docker run -d -p 9191:9191 -e AUTH_METHOD=GitHubToken -e TOKEN=$GITHUB_TOKEN -e SOURCENAME=git -e CONFIG_URI=git@github.com:myorg/myrepo.git configrd/configrd-service

  

Sample docker run with AWS CodeCommit git credentials

    
docker run -d -p 9191:9191 -e AUTH_METHOD=CodeCommitGitCreds -e SOURCENAME=git -e CONFIG_URI=git@github.com:myorg/myrepo.git -e USER=$GIT_USER -e SECRET=$GIT_SECRET configrd/configrd-service

  

Sample docker run with AWS CodeCommit ssh public key authentication and ssh protocol.

Note the AWS git ssh key id must be provided as the username of the ssh URI to the repository.

    
docker run -d -p 9191:9191 -e AUTH_METHOD=SshPubKey -e PK=~/.ssh/rsa_id -e SOURCENAME=git -e CONFIG_URI=ssh://my-aws-ssh-key-id@git-codecommit.us-west-2.amazonaws.com/v1/repos/myrepo configrd/configrd-service

  
Tags: