README.md

concourse-consul-kv-resource

A Concourse resource for interacting with Consul's KV store.

concourse-consul-kv-resource can be used to get or set a key/value in Consul's KV store.

Source configuration

• host: Required. The Consul host.
• key: Required. The Consul key to interact with. Note that all URL path parts following /v1/kv are required. For example, if your key is my-consul:8500/v1/kv/my/key, then key should be "my/key".
• token: Optional. A Consul ACL token.
• tls_cert: Optional. A TLS cert for the Consul.
• tls_key: Optional. A TLS cert key for the Consul.
• ca: Optional. A CA cert for the Consul.
• port: Optional. The port on which the Consul API is hosted. Defaults to 8500.
• protocol: Optional. The protocol to use in calling the Consul API. Defaults to https.
• skip_cert_check: Optional. Check the validity of the SSL cert.

Behavior

in: Get a Consul KV key's value

Gets the value of the Consul KV key configured in the source. The key's plain text value is written to a <resource-get>/<key-name> file.

For example, the following pipeline's get-my-consul-key job writes the foo key's value to a my-consul-key/my/key file:

...

resources:

- name: my-consul-key
  type: consul-kv
  source:
    token: my-acl-token
    host: my-consul.com
    tls_cert: my-cert-string
    tls_key: my-cert-key-string
    key: my/key

jobs:

- name: get-my-consul-key
  plan:
  - get: my-consul-key

out: Set a Consul KV key's value

Sets the Consul KV key configured in the source to the value specified in the params.

Parameters

value or file must be set. Both cannot be set.

• value: Optional. The value to set the key to.
• file: Optional. The path to a file in which the intended value is written.

Example pipeline

resources:

- name: my-consul-key
  type: consul-kv
  source:
    token: my-acl-token
    host: my-consul.com
    tls_cert: my-cert-string
    tls_key: my-cert-key-string
    key: my/key

resource_types:

- name: consul-kv
  type: docker-image
  source:
    repository: clapclapexcitement/concourse-consul-kv-resource
    tag: latest

jobs:

- name: get-my-consul-key
  plan:
  - get: my-consul-key

- name: set-my-consul-key
  plan:
  - put: my-consul-key
    params:
      value: 'foobar'

- name: set-my-consul-key-from-a-file
  plan:
  - put: my-consul-key
    params:
      file: my-new-key/my-key-file

Development & testing

concourse-consul-kv-resource development assumes relative familiarity with Node.js and Docker.

To build and test concourse-consul-kv-resource:

make

This...

1. builds a concourse-consul-kv-resource Docker image by...
   1. installing the Node.js JavaScript dependencies
   2. linting the Node.js JavaScript source code
   3. running the Node.js JavaScript-based unit tests
   4. installing the concourse-consul-kv-resource Node.js JavaScript source code in the resulting Docker image
2. runs a suite of acceptance tests against the resulting concourse-consul-kv-resource Docker image that...
   1. use docker-compose to start a local Consul seeded with a my/key key
   2. run the concourse-consul-kv-resource Docker image with various standard input stream JSON structures and arguments that exercise the image's check, in, and out functionality using the local Consul

Functional testing

concourse-consul-kv-resource's docker-compose.yml can also be used to start a local Concourse, Consul, and Docker registry for test driving a local concourse-consul-kv-resource Docker image build.

1. run docker-compose up to start a localhost:8080 Concourse, a localhost:5000 Docker registry, and a localhost:8500 Consul.
2. build a local localhost:5000/concourse-consul-kv-resource:latest concourse-consul-kv-resource image and publish it to the localhost:5000 Docker registry:

   docker build --tag \
     localhost:5000/concourse-consul-kv-resource:latest .

   docker login \
     --username test \
     --password test \
     http://localhost:5000 \

   docker push \
     localhost:5000/concourse-consul-kv-resource:latest

3. Download the appropriate fly for your platform from the Concourse homepage; make it executable. For example:

   curl \
     --output fly \
     http://localhost:8080/api/v1/cli\?arch\=amd64\&platform\=darwin
   
   chmod +x fly

4. log into the localhost:8080 Concourse via fly using the username/password combo test/test:

   ./fly \
     --target "local" login \
     --username test \
     --password test \
     --concourse-url http://localhost:8080

5. use the pipeline.yml in this repo to set and unpause a test pipeline:

   ./fly \
     --target local set-pipeline \
     --pipeline test \
     --config pipeline.yml \
     --non-interactive

   ./fly \
     --target local unpause-pipeline \
     --pipeline test

6. log into the localhost:8080 Concourse in your web browser using username/password test/test and interact with the test pipeline. If you'd like to seed Consul with an initial my/key value:

   curl \
     --request PUT \
     --data my-value \
     http://localhost:8500/v1/kv/my-key