Skip to content

Commit 1e4fe18

Browse files
digisergdigiserg
authored
Improve documentation (#28)
1 parent 8be7931 commit 1e4fe18

File tree

11 files changed

+2391
-0
lines changed

11 files changed

+2391
-0
lines changed

‎README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,25 @@ dynamic_snitch_reset_interval: 600000ms
3030
3131
This makes coding the ansible playbook to support both versions more complex. Before running this playbook, you'll need to review the variables from [roles/cassandra/defaults/main.yml](roles/cassandra/defaults/main.yml) and compare them against [roles/cassandra/templates/5.0.x/cassandra.yaml.j2](roles/cassandra/templates/5.0.x/cassandra.yaml.j2).
3232
33+
## Role Documentation
34+
35+
This collection provides the following Ansible roles. Click on each role for detailed documentation, configuration options, and examples:
36+
37+
### AxonOps Components
38+
- **[agent](docs/roles/agent.md)** - Install and configure AxonOps Agent for Cassandra monitoring
39+
- **[server](docs/roles/server.md)** - Install and configure AxonOps Server (self-hosted deployments)
40+
- **[dash](docs/roles/dash.md)** - Install and configure AxonOps Dashboard web interface
41+
- **[alerts](docs/roles/alerts.md)** - Configure alerts, integrations, and monitoring settings
42+
43+
### Infrastructure Components
44+
- **[cassandra](docs/roles/cassandra.md)** - Install and configure Apache Cassandra (3.11, 4.x, 5.x)
45+
- **[elastic](docs/roles/elastic.md)** - Install and configure Elasticsearch for AxonOps
46+
- **[java](docs/roles/java.md)** - Install Java (OpenJDK or Azul Zulu)
47+
48+
### Utilities
49+
- **[preflight](docs/roles/preflight.md)** - Run pre-installation system checks
50+
51+
For a complete guide including deployment patterns and quick references, see the [Role Documentation Index](docs/roles/README.md).
3352
3453
## Playbooks
3554

‎docs/roles/README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# AxonOps Ansible Collection - Role Documentation
2+
3+
This directory contains detailed documentation for each role in the AxonOps Ansible Collection.
4+
5+
## Available Roles
6+
7+
### Core AxonOps Components
8+
9+
#### [agent](agent.md)
10+
Installs and configures the AxonOps Agent on Cassandra nodes for monitoring and metric collection.
11+
12+
**Use when**: You want to monitor your Cassandra cluster with AxonOps (required on all Cassandra nodes).
13+
14+
#### [server](server.md)
15+
Installs and configures the AxonOps Server for self-hosted deployments.
16+
17+
**Use when**: You're deploying AxonOps on-premises instead of using the SaaS offering.
18+
19+
#### [dash](dash.md)
20+
Installs and configures the AxonOps Dashboard web interface.
21+
22+
**Use when**: You're deploying a self-hosted AxonOps Server and need the web UI (typically installed alongside the server).
23+
24+
#### [alerts](alerts.md)
25+
Configures alerts, integrations, and monitoring settings for AxonOps.
26+
27+
**Use when**: You need to automate the configuration of alerts, Slack/PagerDuty integrations, or backup policies.
28+
29+
### Infrastructure Components
30+
31+
#### [cassandra](cassandra.md)
32+
Installs and configures Apache Cassandra (versions 3.11, 4.x, and 5.x).
33+
34+
**Use when**: You need to deploy new Cassandra nodes or manage existing installations.
35+
36+
#### [elastic](elastic.md)
37+
Installs and configures Elasticsearch for AxonOps Server configuration storage.
38+
39+
**Use when**: Deploying a self-hosted AxonOps Server (Elasticsearch stores AxonOps configuration data).
40+
41+
#### [java](java.md)
42+
Installs Java (OpenJDK or Azul Zulu) on target systems.
43+
44+
**Use when**: Deploying Cassandra, Elasticsearch, or any Java-dependent component.
45+
46+
### Utility Roles
47+
48+
#### [preflight](preflight.md)
49+
Performs pre-installation checks to ensure systems meet requirements.
50+
51+
**Use when**: Before deploying Cassandra or AxonOps components to validate system readiness.
52+
53+
## Quick Reference
54+
55+
| Role | Purpose | Typically Used With |
56+
|------|---------|-------------------|
57+
| **agent** | Monitor Cassandra clusters | Cassandra nodes |
58+
| **server** | Self-hosted AxonOps backend | Elastic, Cassandra (optional) |
59+
| **dash** | Web UI for AxonOps | Server |
60+
| **alerts** | Alert configuration | Server |
61+
| **cassandra** | Apache Cassandra installation | Agent, Java |
62+
| **elastic** | Elasticsearch installation | Server |
63+
| **java** | Java installation | Cassandra, Elastic |
64+
| **preflight** | System validation | Before any installation |
65+
66+
## Common Deployment Patterns
67+
68+
### Pattern 1: Monitor Existing Cassandra Cluster (SaaS)
69+
70+
Deploy AxonOps Agent on existing Cassandra nodes to monitor with AxonOps SaaS:
71+
72+
```yaml
73+
- hosts: cassandra
74+
roles:
75+
- agent
76+
```
77+
78+
**Roles needed**: `agent`
79+
80+
**See**: [agent.md](agent.md)
81+
82+
---
83+
84+
### Pattern 2: New Cassandra Cluster with Monitoring (SaaS)
85+
86+
Deploy new Cassandra cluster with AxonOps monitoring:
87+
88+
```yaml
89+
- hosts: cassandra
90+
roles:
91+
- preflight
92+
- java
93+
- agent
94+
- cassandra
95+
```
96+
97+
**Roles needed**: `preflight`, `java`, `agent`, `cassandra`
98+
99+
**See**: [cassandra.md](cassandra.md), [agent.md](agent.md), [java.md](java.md), [preflight.md](preflight.md)
100+
101+
---
102+
103+
### Pattern 3: Self-Hosted AxonOps Server
104+
105+
Deploy complete self-hosted AxonOps stack:
106+
107+
```yaml
108+
- hosts: axon-server
109+
roles:
110+
- java
111+
- elastic
112+
- cassandra # Optional: for metrics storage
113+
- server
114+
- dash
115+
```
116+
117+
**Roles needed**: `java`, `elastic`, `server`, `dash`, optionally `cassandra`
118+
119+
**See**: [server.md](server.md), [elastic.md](elastic.md), [dash.md](dash.md)
120+
121+
---
122+
123+
### Pattern 4: Complete Infrastructure
124+
125+
Deploy both AxonOps Server and monitored Cassandra cluster:
126+
127+
**Server host**:
128+
```yaml
129+
- hosts: axon-server
130+
roles:
131+
- java
132+
- elastic
133+
- cassandra
134+
- agent
135+
- server
136+
- dash
137+
```
138+
139+
**Cassandra hosts**:
140+
```yaml
141+
- hosts: cassandra
142+
roles:
143+
- preflight
144+
- java
145+
- agent
146+
- cassandra
147+
```
148+
149+
**Roles needed**: All roles
150+
151+
---
152+
153+
### Pattern 5: Alert Configuration
154+
155+
Configure alerts and integrations for existing AxonOps deployment:
156+
157+
```yaml
158+
- hosts: localhost
159+
roles:
160+
- alerts
161+
```
162+
163+
**Roles needed**: `alerts`
164+
165+
**See**: [alerts.md](alerts.md)
166+
167+
## Getting Started
168+
169+
1. **Choose your deployment pattern** from the list above
170+
2. **Read the documentation** for each role you'll use
171+
3. **Review the example playbooks** in each role's documentation
172+
4. **Customize variables** to match your environment
173+
5. **Run preflight checks** before deploying Cassandra
174+
6. **Deploy in stages** (infrastructure first, then applications, then configuration)
175+
176+
## Additional Resources
177+
178+
- [Main README](../../README.md) - Collection overview and installation
179+
- [Examples Directory](../../examples/) - Complete example playbooks
180+
- [AxonOps Documentation](https://docs.axonops.com/) - Official AxonOps documentation
181+
- [ALERTS.md](../../ALERTS.md) - Alert configuration guide
182+
183+
## Support
184+
185+
For issues, questions, or contributions:
186+
- GitHub Issues: [axonops-ansible-collection](https://github.com/axonops/axonops-ansible-collection/issues)
187+
- AxonOps Support: [support@axonops.com](mailto:support@axonops.com)
188+
- Community Slack: [axonops.slack.com](https://axonops.slack.com)
189+
190+
## License
191+
192+
See the [LICENSE](../../LICENSE) file in the repository root.

‎docs/roles/agent.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# AxonOps Agent Role
2+
3+
## Overview
4+
5+
The `agent` role installs and configures the AxonOps Agent on Cassandra nodes. The AxonOps Agent collects metrics, logs, and diagnostic information from your Apache Cassandra or DataStax Enterprise (DSE) clusters and sends them to the AxonOps Server for monitoring and analysis.
6+
7+
## Requirements
8+
9+
- Ansible 2.9 or higher
10+
- Target system running a supported Linux distribution (RHEL, CentOS, Ubuntu, Debian)
11+
- Apache Cassandra or DataStax Enterprise installed (or install it using the `cassandra` role)
12+
- Network connectivity to AxonOps Server (self-hosted or SaaS)
13+
14+
## Role Variables
15+
16+
### Required Variables
17+
18+
| Variable | Description | Example |
19+
|----------|-------------|---------|
20+
| `axon_agent_server_host` | Server name or IP where the AxonOps server is running | `agents.axonops.cloud` or `192.168.1.10` |
21+
| `axon_agent_customer_name` | Organization name to identify your deployment | `mycompany` |
22+
23+
### Java Agent Configuration
24+
25+
| Variable | Default | Description |
26+
|----------|---------|-------------|
27+
| `axon_java_agent` | `axon-cassandra5.0-agent-jdk17` | Java agent version to install. Options: `axon-cassandra3.11-agent`, `axon-cassandra4.1-agent`, `axon-cassandra5.0-agent-jdk17`, `axon-dse6.0-agent`, `axon-dse6.7-agent`, `axon-dse5.1-agent`, or empty string to skip |
28+
| `axon_agent_version` | `2.0.2` | Version of the AxonOps agent to install |
29+
| `axon_java_agent_version` | `1.0.10` | Version of the Java agent to install |
30+
31+
### Network Configuration
32+
33+
| Variable | Default | Description |
34+
|----------|---------|-------------|
35+
| `axon_agent_server_port` | `443` (SaaS) or `1888` (self-hosted) | Port to connect to AxonOps Server |
36+
| `axon_agent_host_name` | `{{ ansible_hostname }}` | Override the agent hostname if needed |
37+
38+
### TLS Configuration
39+
40+
| Variable | Default | Description |
41+
|----------|---------|-------------|
42+
| `axon_agent_tls_mode` | `disabled` | TLS mode: `disabled`, `TLS`, or `mTLS` |
43+
| `axon_agent_tls_certfile` | - | Path to TLS certificate file (required for TLS/mTLS) |
44+
| `axon_agent_tls_keyfile` | - | Path to TLS key file (required for TLS/mTLS) |
45+
| `axon_agent_tls_cafile` | - | Path to CA certificate file (required for mTLS) |
46+
47+
### Other Variables
48+
49+
| Variable | Default | Description |
50+
|----------|---------|-------------|
51+
| `axon_agent_start_at_boot` | `true` | Enable the agent to start at boot |
52+
| `axon_agent_state` | `present` | State of the agent: `present` or `absent` |
53+
| `axon_agent_ntp_server` | `pool.ntp.org` | NTP server for time synchronization |
54+
55+
## Dependencies
56+
57+
None
58+
59+
## Example Playbooks
60+
61+
### Basic Agent Installation with SaaS
62+
63+
```yaml
64+
- name: Install AxonOps Agent for SaaS
65+
hosts: cassandra
66+
become: true
67+
vars:
68+
axon_agent_customer_name: mycompany
69+
axon_java_agent: "axon-cassandra4.1-agent"
70+
71+
roles:
72+
- role: axonops.axonops.agent
73+
```
74+
75+
### Agent with Self-Hosted Server
76+
77+
```yaml
78+
- name: Install AxonOps Agent with Self-Hosted Server
79+
hosts: cassandra
80+
become: true
81+
vars:
82+
axon_agent_server_host: "{{ groups['axon-server'] | first }}"
83+
axon_agent_customer_name: mycompany
84+
axon_java_agent: "axon-cassandra5.0-agent-jdk17"
85+
axon_agent_version: "2.0.2"
86+
axon_java_agent_version: "1.0.10"
87+
88+
roles:
89+
- role: axonops.axonops.agent
90+
tags: agent
91+
```
92+
93+
### Agent with TLS Enabled
94+
95+
```yaml
96+
- name: Install AxonOps Agent with TLS
97+
hosts: cassandra
98+
become: true
99+
vars:
100+
axon_agent_server_host: axon-server.example.com
101+
axon_agent_customer_name: mycompany
102+
axon_java_agent: "axon-cassandra4.1-agent"
103+
axon_agent_tls_mode: "TLS"
104+
axon_agent_tls_certfile: /etc/axonops/certs/agent.crt
105+
axon_agent_tls_keyfile: /etc/axonops/certs/agent.key
106+
axon_agent_tls_cafile: /etc/axonops/certs/ca.crt
107+
108+
roles:
109+
- role: axonops.axonops.agent
110+
```
111+
112+
### Complete Stack: Java, Agent, and Cassandra
113+
114+
```yaml
115+
- name: Deploy Complete Cassandra Stack with AxonOps
116+
hosts: cassandra
117+
become: true
118+
vars:
119+
axon_agent_server_host: "{{ groups['axon-server'] | first }}"
120+
axon_agent_customer_name: mycompany
121+
axon_java_agent: "axon-cassandra4.1-agent"
122+
java_pkg: java-11-openjdk-headless
123+
cassandra_dc: "DC1"
124+
cassandra_cluster_name: "production"
125+
cassandra_seeds: "{{ groups['cassandra'] | map('extract', hostvars, ['ansible_default_ipv4', 'address']) | list | first }}"
126+
127+
roles:
128+
- role: axonops.axonops.java
129+
tags: java
130+
131+
- role: axonops.axonops.agent
132+
tags: agent
133+
134+
- role: axonops.axonops.cassandra
135+
tags: cassandra
136+
```
137+
138+
## Notes
139+
140+
- **Sudoers Configuration**: The role automatically configures sudo permissions for the axonops user to manage the Cassandra service
141+
- **Service Configuration**: By default, the role does not include the service-specific configuration in `axon-agent.yml` unless `axon_agent_include_service_config` is set to `true`
142+
- **Repository Management**: The role supports public, beta, and dev repositories. Use `axon_agent_public_repository`, `axon_agent_beta_repository`, and `axon_agent_dev_repository` to control which repositories are enabled
143+
- **Offline Installation**: For air-gapped environments, set `has_internet_access: false` and `axon_java_agent_force_offline_install: true`
144+
145+
## Tags
146+
147+
- `agent`: Apply all agent tasks
148+
- `axonops-agent`: Alias for agent tag
149+
150+
## License
151+
152+
See the main collection LICENSE file.
153+
154+
## Author
155+
156+
AxonOps Limited

0 commit comments

Comments
 (0)