Ansible role for Linux deployment (#392)

Initial version of the Ansible role for Linux deployment with tests

.github/workflows/ansible-role-test.yml

@@ -0,0 +1,62 @@
+on: 
+  pull_request:
+    paths:
+      - 'deployments/ansible/roles/splunk-otel-collector/**'
+
+defaults:
+  run:
+    working-directory: 'deployments/ansible/roles/splunk-otel-collector'
+
+jobs:
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out the codebase.
+        uses: actions/checkout@v2
+
+      - name: Set up Python 3.
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+
+      - name: Install yamllint.
+        run: pip3 install yamllint
+
+      - name: Lint code.
+        run: yamllint .
+
+  molecule-test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        distro:
+          - amazonlinux2
+          - centos7
+          - centos8
+          - debian9
+          - debian10
+          - ubuntu1604
+          - ubuntu1804
+          - ubuntu2004
+
+    steps:
+      - name: Check out the codebase.
+        uses: actions/checkout@v2
+
+      - name: Set up Python 3.
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.x'
+
+      - name: Install test dependencies.
+        run: pip3 install ansible molecule[docker] docker
+
+      - name: Run Molecule tests.
+        run: molecule --base-config ./molecule/config/docker.yml test --all
+        env:
+          PY_COLORS: '1'
+          ANSIBLE_FORCE_COLOR: '1'
+          MOLECULE_DISTRO: ${{ matrix.distro }}

.gitignore

@@ -32,3 +32,6 @@ venv/
 __pycache__
 *.pyc
 .pytest_cache
+
+# Ansible Molecule
+.cache

deployments/ansible/roles/splunk-otel-collector/.yamllint

@@ -0,0 +1,12 @@
+---
+# Based on ansible-lint config
+extends: default
+
+rules:
+  line-length:
+    max: 120
+    level: error
+  key-duplicates: enable
+  new-lines:
+    type: unix
+  truthy: disable

deployments/ansible/roles/splunk-otel-collector/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing Guidelines
+
+If you found a bug in the Ansible role, don't hesitate to submit an issue or a 
+pull request.
+
+## Local development
+
+Testing and validation of this Ansible role is based on 
+[Ansible Molecule](https://molecule.readthedocs.io/en/latest/).
+
+### MacOS or Windows setup
+
+Development of the role can be done on MacOS or Windows machines. Make sure the
+following software is installed:
+
+- [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
+- [Vagrant](https://www.vagrantup.com/downloads)
+- [Python3](https://www.python.org/downloads)
+- Python packages:
+  - ansible 
+  - molecule
+  - molecule-vagrant
+  - python-vagrant
+
+Installation steps for MacOS:
+
+```sh
+brew tap hashicorp/tap
+brew install virtualbox vagrant python3
+pip3 install -r requirements-dev-macos.txt
+```
+
+Use the following arguments with every molecule command 
+`--base-config ./molecule/config/vagrant.yml`.
+
+To setup test VMs:
+```sh
+molecule --base-config ./molecule/config/vagrant.yml create
+```
+
+To apply Molecule test playbooks:
+```sh
+molecule --base-config ./molecule/config/vagrant.yml converge
+```
+
+To run the full test suite:
+```sh
+molecule --base-config ./molecule/config/vagrant.yml test --all
+```
+
+### Linux setup
+
+Development on a Linux machine is simpler, all you need is docker. 
+
+Make sure the following software is installed:
+
+- [Docker](https://docs.docker.com/get-docker/)
+- [Python3](https://www.python.org/downloads)
+- Python packages:
+  - ansible 
+  - molecule
+  - molecule-docker
+
+Installation steps for Linux:
+
+1. Make sure Python 3 and [pip](https://pip.pypa.io/en/stable/installing/) are installed : `pip3 --version`
+1. Make sure Docker is installed and can be managed by the current user: `docker ps`
+1. Install python packages: `pip3 install -r requirements-dev-linux.txt`
+
+Use the following arguments with every molecule command 
+`--base-config ./molecule/config/docker.yml`.
+
+To setup test docker containers:
+```sh
+molecule --base-config ./molecule/config/docker.yml create
+```
+
+To apply Molecule playbooks:
+```sh
+molecule --base-config ./molecule/config/docker.yml converge
+```
+
+To run the full test suite:
+```sh
+molecule --base-config ./molecule/config/docker.yml test --all
+```

deployments/ansible/roles/splunk-otel-collector/README.md

@@ -0,0 +1,119 @@
+# Splunk OpenTelemetry Connector Ansible Role
+
+Ansible role that installs Splunk OpenTelemetry Connector configured to
+collect metrics, traces and logs from Linux machines and send data to [Splunk 
+Observability Cloud](https://www.splunk.com/en_us/observability.html). 
+
+## Prerequisites
+
+- [Splunk Access Token](https://docs.splunk.com/Observability/admin/authentication-tokens/org-tokens.html#admin-org-tokens)
+- [Splunk Realm](https://dev.splunk.com/observability/docs/realms_in_endpoints/)
+- [Double-check exposed ports](https://github.com/signalfx/splunk-otel-collector/blob/main/docs/security.md#exposed-endpoints) 
+  to make sure your environment doesn't have conflicts. Ports can be changed in the collector's configuration.
+
+## Usage
+
+To install the role, clone the repo to your control host and add the 
+`.deployments/ansible/roles/splunk-otel-collector` directory to `roles_path` in 
+`ansible.cfg`, or use this document's directory as your working directory.
+
+To use this role, simply include the `splunk-otel-collector` role invocation 
+in your playbook. The following example shows how to use the role in a
+playbook with minimal required configuration:
+
+```yaml
+- name: Install Splunk OpenTelemetry Connector
+  hosts: all
+  become: yes
+  vars:
+    splunk_access_token: YOUR_ACCESS_TOKEN
+    splunk_realm: SPLUNK_REALM
+  tasks:
+    - name: "Include splunk-otel-collector"
+      include_role:
+        name: "splunk-otel-collector"
+```
+
+## Role Variables
+
+- `splunk_access_token` (**Required**): The Splunk access token to
+  authenticate requests.
+
+- `splunk_realm`: Which realm to send the data to. The `SPLUNK_REALM`
+  environment variable will be set with this value for the Splunk OTel 
+  Collector service. (**default:** `us0`)
+
+- `splunk_ingest_url`: The Splunk ingest URL, e.g.
+  `https://ingest.us0.signalfx.com`. The `SPLUNK_INGEST_URL` environment
+  variable will be set with this value for the collector service. (**default:**
+  `https://ingest.{{ splunk_realm }}.signalfx.com`)
+
+- `splunk_api_url`: The Splunk API URL, e.g. `https://api.us0.signalfx.com`.
+  The `SPLUNK_API_URL` environment variable will be set with this value for the
+  collector service. (**default:** `https://api.{{ splunk_realm }}.signalfx.com`)
+
+- `collector_version`: Version of the collector package to install, e.g.
+  `0.25.0`. (**default:** `latest`)
+
+- `collector_config`: Splunk OTel Collector config YAML file. Can be set to 
+  `/etc/otel/collector/gateway_config.yaml` to install the collector in gateway
+  mode. (**default:** `/etc/otel/collector/agent_config.yaml`)
+
+- `collector_config_source`: Source path to a Splunk OTel Collector config YAML 
+  file on your control host that will be uploaded and set in place of
+  `collector_config` in remote hosts. Can be used to submit a custom collector 
+  config, e.g. `./custom_collector_config.yaml`. (**default:** `""` meaning 
+  that nothing will be copied and existing `collector_config` will be used)
+
+- `splunk_bundle_dir`: The path to the [Smart Agent bundle directory](
+  https://github.com/signalfx/splunk-otel-collector/blob/main/internal/extension/smartagentextension/README.md).
+  The default path is provided by the collector package. If the specified path
+  is changed from the default value, the path should be an existing directory
+  on the node. The `SPLUNK_BUNDLE_DIR` environment variable will be set to
+  this value for the collector service.  (**default:**
+  `/usr/lib/splunk-otel-collector/agent-bundle`)
+
+- `splunk_collectd_dir`: The path to the collectd config directory for the
+  Smart Agent bundle. The default path is provided by the collector package.
+  If the specified path is changed from the default value, the path should be
+  an existing directory on the node. The `SPLUNK_COLLECTD_DIR` environment
+  variable will be set to this value for the collector service.  (**default:**
+  `/usr/lib/splunk-otel-collector/agent-bundle`)
+
+- `service_user` and `service_group` (Linux only): Set the user/group
+  ownership for the collector service. The user/group will be created if they
+  do not exist. (**default:** `splunk-otel-collector`)
+
+- `memory_total_mib`: Amount of memory in MiB allocated to the Splunk OTel 
+  Collector. (**default:** `512`)
+
+- `ballast_size_mib`: Memory ballast size in MiB that will be set to the Splunk 
+  OTel Collector. (**default:** 1/3 of `memory_total_mib`)
+
+- `install_fluentd`: Whether to install/manage fluentd and dependencies for log
+  collection. The dependencies include [capng_c](
+  https://github.com/fluent-plugins-nursery/capng_c) for enabling
+  [Linux capabilities](
+  https://docs.fluentd.org/deployment/linux-capability),
+  [fluent-plugin-systemd](
+  https://github.com/fluent-plugin-systemd/fluent-plugin-systemd) for systemd
+  journal log collection, and the required libraries/development tools.
+  (**default:** `true`)
+
+- `td_agent_version`: Version of td-agent (fluentd package) that will be 
+  installed (**default:** `3.3.0` for Debian jessie, `3.7.1` for Debian 
+  stretch, and `4.1.1` for other distros`)
+
+- `fluentd_config`: Path to the fluentd config file on the remote host.
+  (**default:** `/etc/otel/collector/fluentd/fluent.conf`)
+
+- `fluentd_config_source`: Source path to a fluentd config file on your 
+  control host that will be uploaded and set in place of `fluentd_config` on
+  remote hosts. Can be used to submit a custom fluentd config,
+  e.g. `./custom_fluentd_config.conf`. (**default:** `""` meaning 
+  that nothing will be copied and existing `fluentd_config` will be used)
+
+## Contributing
+
+Check [Contributing guidelines](./CONTRIBUTING.md) if you see something that 
+needs to be improved in this Ansible role.

deployments/ansible/roles/splunk-otel-collector/defaults/main.yml

@@ -0,0 +1,35 @@
+---
+# defaults file for splunk-otel-collector role vars
+
+# splunk_access_token is REQUIRED variable
+splunk_access_token: ""
+
+splunk_realm: us0
+
+collector_version: latest
+
+# Set this variable to /etc/otel/collector/gateway_config.yaml in order to
+# deploy splunk-otel-collector in gateway mode
+collector_config: /etc/otel/collector/agent_config.yaml
+# Set collector_config_source to copy a custom config from a local path
+collector_config_source: ""
+
+service_user: splunk-otel-collector
+service_group: splunk-otel-collector
+
+memory_total_mib: 512
+# 1/3 of memory_mib by default
+ballast_size_mib: ""
+
+install_fluentd: true
+
+# Explicitly set version of td-agent,
+# By default: 3.3.0 for Debian jessie, 3.7.1 for Debian stretch,
+# and 4.1.1 for other distros.
+td_agent_version: ""
+
+fluentd_config: /etc/otel/collector/fluentd/fluent.conf
+fluentd_config_source: ""
+
+agent_bundle_dir: /usr/lib/splunk-otel-collector/agent-bundle
+splunk_collectd_dir: /usr/lib/splunk-otel-collector/agent-bundle/run/collectd

deployments/ansible/roles/splunk-otel-collector/handlers/main.yml

@@ -0,0 +1,22 @@
+---
+# handlers file for splunk-otel-collector
+
+- name: Reload systemd daemon
+  ansible.builtin.systemd:
+    daemon_reload: yes
+  listen:
+    - restart splunk-otel-collector
+    - restart td-agent
+
+- name: Restart td-agent
+  ansible.builtin.service:
+    name: td-agent
+    state: restarted
+  when: install_fluentd
+  listen: "restart td-agent"
+
+- name: Restart Splunk OpenTelemetry Collector
+  ansible.builtin.service:
+    name: splunk-otel-collector
+    state: restarted
+  listen: "restart splunk-otel-collector"

deployments/ansible/roles/splunk-otel-collector/molecule/config/docker.yml

@@ -0,0 +1,17 @@
+---
+# molecule config based on docker for CI usage on a Linux system only
+
+driver:
+  name: docker
+platforms:
+  - name: instance
+    image: "geerlingguy/docker-${MOLECULE_DISTRO:-centos8}-ansible:latest"
+    command: ${MOLECULE_DOCKER_COMMAND:-""}
+    volumes:
+      - /sys/fs/cgroup:/sys/fs/cgroup:ro
+    privileged: true
+    pre_build_image: true
+provisioner:
+  name: ansible
+  playbooks:
+    converge: ${MOLECULE_PLAYBOOK:-converge.yml}

deployments/ansible/roles/splunk-otel-collector/molecule/config/vagrant.yml

@@ -0,0 +1,18 @@
+---
+# molecule config based on vagrant and virtualbox for local usage on any OS
+
+driver:
+  name: vagrant
+  provider:
+    name: virtualbox
+platforms:
+  - name: focal64
+    box: ubuntu/focal64
+  - name: centos8
+    box: centos/8
+  - name: buster64
+    box: debian/buster64
+  - name: amazonlinux
+    box: bento/amazonlinux-2
+provisioner:
+  name: ansible