Create role subdirectory

Per Ansible Collection documentation, the conjur_host_identity role has been moved to a `role` subdirectory. A `tests` subdirectory has been added for this role, and all relevant tests moved there.
cyberark · Sep 24, 2020 · 54e6955 · 54e6955
1 parent a768495
commit 54e6955
Show file tree

Hide file tree

Showing 63 changed files with 181 additions and 221 deletions.
diff --git a/.gitleaks.toml b/.gitleaks.toml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,15 +7,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ## [Unreleased]
 
 ### Added
-- The Ansible [conjur-host-identity](https://galaxy.ansible.com/cyberark/conjur-host-identity) has  
-  been migrated to this collection, where it will be maintained moving forward. [cyberark/
-  conjur-host-identity#30](https://github.com/cyberark/ansible-conjur-host-identity/issues/30)
-
-### Changed
-- [Added retries](https://github.com/cyberark/ansible-conjur-host-identity/pull/32) to tasks/  
-  identity/Request identity from Conjur.
+- The [Conjur Ansible role](https://galaxy.ansible.com/cyberark/conjur-host-identity) has been
+  migrated to this collection, where it will be maintained moving forward.
+  [cyberark/ansible-conjur-host-identity#30](https://github.com/cyberark/ansible-conjur-host-identity/issues/30)
+- Added retries to tasks/identity/Request identity from Conjur.
   This will increase the reliability of host factory requests without introducing any extra delay 
   if the first request succeeds.
+  [cyberark/ansible-conjur-host-identity#32](https://github.com/cyberark/ansible-conjur-host-identity/pull/32)
 
 ## [1.0.7] - 2020-08-20
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -27,9 +27,15 @@ of this plugin:
 
 ### Testing
 
-To run the tests:
+To run a specific set of tests:
 
 ```sh-session
 $ cd tests
-$ ./test.sh <conjur or conjur-host-identity>
+$ ./test.sh -d <role or plugin name>
 ```
+To run all tests:
+
+```sh-session
+$ cd tests
+$ ./test.sh -a
+```
diff --git a/Jenkinsfile b/Jenkinsfile
@@ -20,19 +20,19 @@ pipeline {
 
     stage('Run tests') {
       parallel {
-        stage("Test Ansible-Conjur-Collection") {
+        stage("Test conjur_lookup Plugin") {
           agent { label 'executor-v2-large' }
 
           steps {
-            sh './ci/test.sh -d conjur'
-            junit 'tests/conjur/junit/*'
+            sh './ci/test.sh -d conjur_variable'
+            junit 'tests/conjur_variable/junit/*'
           }
         }
 
-        stage("Test Ansible-Conjur-Host-Identity") {
+        stage("Test conjur_host_identity Role") {
           steps {
-            sh './ci/test.sh -d conjur-host-identity'
-            junit 'tests/conjur-host-identity/junit/*'
+            sh './ci/test.sh -d conjur_host_identity'
+            junit 'roles/conjur_host_identity/tests/junit/*'
           }
         }
       }

diff --git a/README.md b/README.md
@@ -2,22 +2,23 @@
 
 # CyberArk Ansible Conjur Collection
 
-This collection contains plugins to be used for CyberArk Conjur & DAP (Dynamic Access Provider) hosted in [ansible galaxy](https://galaxy.ansible.com/cyberark/conjur).
+This collection contains components to be used with CyberArk Conjur & DAP (Dynamic Access Provider)
+hosted in [Ansible Galaxy](https://galaxy.ansible.com/cyberark/conjur).
 
 ## Table of Contents
 - [CyberArk Ansible Conjur Collection](#cyberark-ansible-conjur-collection)
   * [Requirements](#requirements)
-  * [conjur_variable Lookup Plugin](#conjur_variable-lookup-plugin)
+  * [Conjur Ansible Role](#conjur-ansible-role)
+    + [Usage](#usage)
     + [Role Variables](#role-variables)
     + [Dependencies](#dependencies)
     + [Example Playbook](#example-playbook)
-  * [Conjur Ansible Role](#conjur-ansible-role)
-    + [Usage](#usage)
+    + [Summon & Service Managers](#summon---service-managers)
+    + [Recommendations](#recommendations)
+  * [conjur_variable Lookup Plugin](#conjur_variable-lookup-plugin)
     + [Role Variables](#role-variables-1)
     + [Dependencies](#dependencies)
     + [Example Playbook](#example-playbook-1)
-    + [Summon & Service Managers](#summon---service-managers)
-    + [Recommendations](#recommendations)
   * [Contributing](#contributing)
   * [License](#license)
 
@@ -26,68 +27,45 @@ http://ecotrust-canada.github.io/markdown-toc/ -->
 
 ## Requirements
 
-- conjur_variable Lookup Plugin
-  - [CyberArk Conjur Open Source](https://www.conjur.org) v1.x+ or
-  - [CyberArk Dynamic Access Provider](https://docs.cyberark.com/Product-Doc/OnlineHelp/AAM-DAP/Latest/en/Content/Resources/_TopNav/cc_Home.htm) v10.x+
-  - Ansible >= 2.9
-
-- Conjur Role
-  - A running Conjur service that is accessible from the target nodes.
-  - Ansible >= 2.3.0.0
+- An instance of [CyberArk Conjur Open Source](https://www.conjur.org) v1.x+ or [CyberArk Dynamic
+  Access
+  Provider](https://docs.cyberark.com/Product-Doc/OnlineHelp/AAM-DAP/Latest/en/Content/Resources/_TopNav/cc_Home.htm)
+  v10.x+ accessible from the target node
+- Ansible >= 2.9
 
 ## Installation 
 From terminal, run the following command:
 ```sh
 ansible-galaxy collection install cyberark.conjur
 ```
 
-## conjur_variable Lookup Plugin
-Fetch credentials from CyberArk Conjur using the controlling host's Conjur identity or environment variables.
-
-- The controlling host running Ansible has a Conjur identity. [More Information here](https://docs.conjur.org/latest/en/Content/Get%20Started/key_concepts/machine_identity.html) and here in [Conjur Ansible role project](https://github.com/cyberark/ansible-conjur-host-identity/)
-
-- Environment variables could be `CONJUR_ACCOUNT`, `CONJUR_APPLIANCE_URL`, `CONJUR_CERT_FILE`, `CONJUR_AUTHN_LOGIN`, `CONJUR_AUTHN_API_KEY`, `CONJUR_AUTHN_TOKEN_FILE`
-
-### Role Variables
-
-None.
-<br>
-
-### Example Playbook
-
-```yaml
----
-- hosts: localhost
-  tasks:
-  - name: Lookup variable in Conjur
-    debug:
-      msg: "{{ lookup('cyberark.conjur.conjur_variable', '/path/to/secret') }}"
-```
-
 ## Conjur Ansible Role
-This Ansible role provides the ability to grant Conjur machine identity to a host. Based on that identity, secrets can then be retrieved securely using the [Summon](https://github.com/cyberark/summon) tool (installed on hosts with identities created by this role).
+This Ansible role provides the ability to grant Conjur machine identity to a host. Based on that
+identity, secrets can then be retrieved securely using the [Conjur Lookup
+Plugin](#conjur_variable-lookup-plugin) or using the [Summon](https://github.com/cyberark/summon)
+tool (installed on hosts with identities created by this role).
 
 ### Usage
-The Conjur role provides a method to "Conjurize" or establish the Conjur identity of a remote node with Ansible. The node can then be granted least-privilege access to retrieve the secrets it needs in a secure manner.
+The Conjur role provides a method to establish the Conjur identity of a remote node with Ansible.
+The node can then be granted least-privilege access to retrieve the secrets it needs in a secure
+manner.
 
 ### Role Variables
 
-* `conjur_appliance_url` `*`: URL of the running Conjur service
-* `conjur_account` `*`: Conjur account name
-* `conjur_host_factory_token` `*`: [Host Factory](https://developer.conjur.net/reference/services/host_factory/) token for
-layer enrollment. This should be specified in the environment on the Ansible controlling host.
-* `conjur_host_name` `*`: Name of the host being conjurized.
+* `conjur_appliance_url` (_Optional)_: URL of the running Conjur service
+* `conjur_account` (_Optional)_: Conjur account name
+* `conjur_host_factory_token` (_Optional)_: [Host
+  Factory](https://developer.conjur.net/reference/services/host_factory/) token for layer
+  enrollment. This should be specified in the environment on the Ansible controlling host.
+* `conjur_host_name` (_Optional)_: Name of the host to be created.
 * `conjur_ssl_certificate`: Public SSL certificate of the Conjur endpoint
-* `conjur_validate_certs`: Boolean value to indicate if the Conjur endpoint should validate certificates
-* `summon.version`: version of Summon to install. Default is `0.6.6`.
-* `summon_conjur.version`: version of Summon-Conjur provider to install. Default is `0.5.0`.
+* `conjur_validate_certs`: Boolean value to indicate if the Conjur endpoint should validate
+  certificates
+* `summon.version`: version of Summon to install. Default is `0.8.2`.
+* `summon_conjur.version`: version of Summon-Conjur provider to install. Default is `0.5.3`.
 
-The variables marked with `*` are required fields. The other variables are required for running with an HTTPS Conjur endpoint, but are not required if you run with an HTTP Conjur endpoint.
-
-### Dependencies
-
-None.
-<br/>
+The variables marked with _`(Optional)`_ are required fields. All other variables are required for
+running with an HTTPS Conjur endpoint.
 
 ### Example Playbook
 
@@ -103,11 +81,13 @@ Configure a remote node with a Conjur identity and Summon:
 ```
 
 This example:
-- Registers the host with Conjur, adding it into the layer specific to the provided host factory token.
+- Registers the host `{insert whatever the hostname is}` with Conjur, adding it into the Conjur 
+policy layer defined for the provided host factory token.
 - Installs Summon with the Summon Conjur provider for secret retrieval from Conjur.
 
 ### Summon & Service Managers
-With Summon installed, using Conjur with a Service Manager (like SystemD) becomes a snap.  Here's a simple example of a SystemD file connecting to Conjur:
+With Summon installed, using Conjur with a Service Manager (like SystemD) becomes a snap.  Here's a
+simple example of a SystemD file connecting to Conjur:
 ```ini
 [Unit]
 Description=DemoApp
@@ -118,24 +98,75 @@ User=DemoUser
 #Environment=CONJUR_MAJOR_VERSION=4
 ExecStart=/usr/local/bin/summon --yaml 'DB_PASSWORD: !var staging/demoapp/database/password' /usr/local/bin/myapp
 ```
-> Note:
-When connecting to Conjur 4 (Conjur Enterprise), Summon requires the environment variable `CONJUR_MAJOR_VERSION` set to `4`. You can provide it by uncommenting the relevant line above.
+> Note: When connecting to Conjur 4 (Conjur Enterprise), Summon requires the environment variable
+`CONJUR_MAJOR_VERSION` set to `4`. You can provide it by uncommenting the relevant line above.
 
-The above example uses Summon to retrieve the password stored in `staging/myapp/database/password`, set it to an environment variable `DB_PASSWORD`, and provide it to the demo application process. Using Summon, the secret is kept off disk. If the service is restarted, Summon retrieves the password as the application is started.
+The above example uses Summon to retrieve the password stored in `staging/myapp/database/password`,
+set it to an environment variable `DB_PASSWORD`, and provide it to the demo application process.
+Using Summon, the secret is kept off disk. If the service is restarted, Summon retrieves the
+password as the application is started.
 
 ### Recommendations
 
-- Add `no_log: true` to each play that uses sensitive data, otherwise that data can be printed to the logs.
+- Add `no_log: true` to each play that uses sensitive data, otherwise that data can be printed to
+  the logs.
+
+- Set the Ansible files to minimum permissions. Ansible uses the permissions of the user that runs
+  it.
+
+## Conjur Ansible Lookup Plugin
+Fetch credentials from CyberArk Conjur using the controlling host's Conjur identity or environment
+variables.
 
-- Set the Ansible files to minimum permissions. Ansible uses the permissions of the user that runs it.
+he controlling host running Ansible must have a Conjur identity, provided for example by the 
+[Conjur Ansible role](#conjur-ansible-role).
+### Environment variables
+
+The following environment variables will be used by the lookup plugin to authenticate with the
+Conjur host, if they are present on the system running the lookup plugin.
+
+- `CONJUR_ACCOUNT` : The Conjur account name
+- `CONJUR_APPLIANCE_URL` : URL of the running Conjur service
+- `CONJUR_CERT_FILE` : Path to the Conjur certificate file
+- `CONJUR_AUTHN_LOGIN` : A valid Conjur host username
+- `CONJUR_AUTHN_API_KEY` : The api key that corresponds to the Conjur host username
+- `CONJUR_AUTHN_TOKEN_FILE` : Path to a file containing a valid Conjur auth token
+
+### Role Variables
+
+None.
+
+### Example Playbook
+
+```yaml
+---
+- hosts: localhost
+  tasks:
+  - name: Lookup variable in Conjur
+    debug:
+      msg: "{{ lookup('cyberark.conjur.conjur_variable', '/path/to/secret') }}"
+```
 
 ## Contributing
 
-We welcome contributions of all kinds to this repository. For instructions on how to get started and descriptions of our development workflows, please see our [contributing
-guide][contrib].
+We welcome contributions of all kinds to this repository. For instructions on how to get started and
+descriptions of our development workflows, please see our [contributing guide][contrib].
 
 [contrib]: https://github.com/cyberark/ansible-conjur-collection/blob/master/CONTRIBUTING.md
 
 ## License
 
-This repository is licensed under Apache License 2.0 - see [`LICENSE`](LICENSE) for more details.
+Copyright (c) 2020 CyberArk Software Ltd. All rights reserved.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+For the full license text see [`LICENSE`](LICENSE).