Skip to content

Latest commit

 

History

History
251 lines (186 loc) · 8.63 KB

CONTRIBUTING.md

File metadata and controls

251 lines (186 loc) · 8.63 KB
Raw

Contributing to the Ansible Conjur Collection

Thanks for your interest in Conjur. Before contributing, please take a moment to read and sign our Contributor Agreement. This provides patent protection for all Conjur users and allows CyberArk to enforce its license terms. Please email a signed copy to oss@cyberark.com. For general contribution and community guidelines, please see the community repo.

Table of contents generated with markdown-toc

Prerequisites

Before getting started, the following tools need to be installed:

  1. Git to manage source code
  2. Docker to manage dependencies and runtime environments
  3. Docker Compose to orchestrate Docker environments

Set up a development environment

The dev directory contains a docker-compose.yml file which creates a development environment :

  • A Conjur Open Source instance
  • An Ansible control node
  • Managed nodes to push tasks to

To use it:

  1. Install dependencies (as above)

  2. To use the dev environment, clone the Collection repository and run the setup script:

    $ git clone https://github.com/cyberark/ansible-conjur-collection.git
$ cd ansible-conjur-collection/dev
$ ./start.sh

Verification

When the Conjur and Ansible containers have been successfully setup, the terminal prints the following:

  ...
  PLAY RECAP *********************************************************************
  ansibleplugingtestingconjurhostidentity-test_app_centos-1 : ok=17 ...
  ansibleplugingtestingconjurhostidentity-test_app_centos-2 : ok=17 ...
  ansibleplugingtestingconjurhostidentity-test_app_ubuntu-1 : ok=16 ...
  ansibleplugingtestingconjurhostidentity-test_app_ubuntu-2 : ok=16 ...

Your Conjur instance will be configured with the following:

  • Account: cucumber
  • User: admin
  • Password: Run conjurctl role retrieve-key cucumber:user:admin inside the Conjur container shell to retrieve the admin user API key

Useful links

Testing

Unit tests

Unit tests are only available for the Conjur Variable Lookup plugin. To run these tests:

./dev/test_unit.sh

Integration tests

The collection has integration tests for both the Variable Lookup plugin and the Host Identity role that will validate each against live Conjur and Ansible containers.

To run all tests:

./ci/test.sh -a

To run the tests for a particular module:

./ci/test.sh -d <role or plugin name>

Integration tests can be run against Conjur Enterprise by adding the -e flag:

./ci/test/sh -e -a

Releasing

From a clean instance of main, perform the following actions to release a new version of this plugin:

  • Update the version number in galaxy.yml and CHANGELOG.md

    • Verify that all changes for this version in CHANGELOG.md are clear and accurate, and are followed by a link to their respective issue
    • Create a PR with these changes

  • Create an annotated tag with the new version, formatted as v##.##.##

    • This will kick off an automated script which publish the release to Ansible Galaxy

  • Create the release on GitHub for that tag

    • Build the release package with ./ci/build_release
    • Attach package to Github Release

Ansible Conjur Collection Quick Start

Setup a conjur OSS Environment

Generate the master key, which will be used to encrypt Conjur's database. Store this value as an environment variable.

docker compose run --no-deps --rm conjur data-key generate > data_key
export CONJUR_DATA_KEY="$(< data_key)"

Start the Conjur OSS environment. An account, named cucumber, will be automatically created.

docker compose up -d conjur

Retrieve the admin user's API key, and store the value in an environment variable.

export CLI_CONJUR_AUTHN_API_KEY="$(docker compose exec conjur conjurctl role retrieve-key cucumber:user:admin)"

Start the Conjur CLI container. The CLI will be automatically authenticated as the user cucumber:user:admin.

docker compose up -d conjur_cli

Load policy to set up Conjur Ansible integration

Policy defines Conjur entities and the relationships between them. An entity can be a policy, a host, a user, a layer, a group, or a variable.

Check out the policy file, and load it into Conjur:

docker compose exec conjur_cli cat /policy/root.yml
docker compose exec conjur_cli conjur policy load root /policy/root.yml

Also, load a dummy secret value into the ansible/target-password variable. This is a variable required by remote nodes in order to complete their workloads.

docker compose exec conjur_cli conjur variable values add ansible/target-password S3cretV@lue

Create Ansible managed nodes

The Ansible environment will include a control node and a number of managed nodes. First, retrieve the API key for the Conjur host representing the control node, then create it:

export ANSIBLE_CONJUR_AUTHN_API_KEY="$(docker compose exec conjur conjurctl role retrieve-key cucumber:host:ansible/ansible-master)"
docker compose up -d ansible

Next, create two instances of each managed node:

docker compose up -d --scale test_app_ubuntu=2 test_app_ubuntu
docker compose up -d --scale test_app_centos=2 test_app_centos

Use Conjur Ansible Role to set up identity on managed nodes

To grant your Ansible host a Conjur identity, first install the Conjur Collection on your Ansible control node:

docker compose exec ansible ansible-galaxy collection install cyberark.conjur

Set up the host factory token in the HFTOKEN env var

export HFTOKEN="$(docker compose exec conjur_cli conjur hostfactory tokens create ansible/ansible-factory | jq -r '.[0].token')"

Once you've done this, you can configure each Ansible node with a Conjur identity by including a section like the example below in your Ansible playbook:

---
- hosts: testapp
  roles:
    - role: cyberark.conjur.conjur_host_identity
      conjur_appliance_url: 'https://conjur.myorg.com',
      conjur_account: 'cucumber',
      conjur_host_factory_token: "{{lookup('env', 'HFTOKEN')}}",
      conjur_host_name: "{{inventory_hostname}}"

First we register the host with Conjur, adding it into the layer specific to the provided host factory token, and then install Summon with the Summon Conjur provider for secret retrieval from Conjur.

Use Conjur Lookup Plugin to provide secrets to Ansible Playbooks

The Conjur lookup plugin can inject secret data directly into an Ansible playbook, like it the following example:

---
- hosts: testapp
  tasks:
  - name: Provide secret with Lookup plugin
    debug:
      msg: "{{ lookup('cyberark.conjur.conjur_variable', '/ansible/target-password') }}"