# Agnosticd

> AI assistance for AgnosticD v2 — the Ansible Agnostic Deployer for provisioning infrastructure and deploying workloads on AWS, Azure, OpenStack, and OpenShift. Use when working with the agd CLI, catalog items, configs, or deployment workflows.

- Skill: `tosin2013/agnosticd` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add tosin2013/agnosticd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tosin2013/agnosticd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- License: Apache-2.0
- Author: tosin2013 (https://skillmd.com/u/tosin2013)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tosin2013/agnosticd

---


# AgnosticD v2 Skill

## When to Use

- Setting up the AgnosticD v2 local development environment
- Running `agd setup`, `agd provision`, `agd destroy`, `agd stop/start/status`
- Creating or modifying configs (infrastructure definitions)
- Creating or modifying workloads (post-deployment customizations)
- Configuring secrets files, variables files, or account credentials
- Working with execution environments and ansible-navigator
- Understanding the required directory structure
- Deploying Field-Sourced Content as an AgnosticD workload
- Configuring Showroom as an infra_workload for lab guides
- Setting up a fork of AgnosticD v2 for workshop development
- Debugging deployment failures

## Instructions

- Read `references/core-workloads-catalog.md` when selecting or configuring workload roles
- Read `references/deployment-scripts.md` when generating deploy/teardown/stop/start scripts
- Read `references/research-questions.md` when encountering a (RESEARCH NEEDED) marker
- The primary CLI is `./bin/agd` — always run it from within the `agnosticd-v2` directory

## Gotchas

- Secrets are NEVER embedded in scripts — they come from `agnosticd-v2-secrets/secrets.yml`
- `students.txt` tracks provisioned GUIDs and must be added to `.gitignore`
- The `agd` CLI must be run from the agnosticd-v2 root directory, not from the config directory
- Config names must match their directory name exactly (case-sensitive)
- `agnosticd_user_info` output is what populates Showroom's `antora.yml` attributes — if data is missing in the lab guide, check `agnosticd_user_info` first
- Tag all cloud resources via `cloud_tags` with at minimum `owner`, `guid`, and `config` — required for RHDP automated cleanup; missing tags cause resources to be orphaned

## Directory Structure

AgnosticD v2 requires this local directory layout (created by `agd setup`):

```
~/Development/              # or any root directory
  agnosticd-v2/             # the code repository
  agnosticd-v2-vars/        # configuration variables files
  agnosticd-v2-secrets/     # secrets.yml + per-account secrets
  agnosticd-v2-output/      # ansible run output (per GUID)
  agnosticd-v2-virtualenv/  # Python 3.12+ venv with ansible-navigator
```

## Fork Workflow

Users developing workshops or custom deployments should **fork** `agnosticd-v2` to their own GitHub org rather than working directly in the upstream repository.

```bash
# Fork via GitHub UI, then clone your fork
git clone https://github.com/your-org/agnosticd-v2.git
cd agnosticd-v2

# Add upstream as a remote for syncing
git remote add upstream https://github.com/agnosticd/agnosticd-v2.git

# Keep your fork in sync
git fetch upstream
git merge upstream/main
```

- **Custom configs and workloads** live in your fork under `ansible/configs/` and `ansible/roles/`
- **Workshop-specific variables** go in `agnosticd-v2-vars/` (outside the repo, never committed)
- **Secrets** go in `agnosticd-v2-secrets/` (outside the repo, never committed)
- **Only generic improvements** (bug fixes, new core features, documentation) should be submitted as PRs to the upstream `agnosticd/agnosticd-v2` repository
- **Never push** workshop-specific configs or workloads to upstream

When configuring `ocp4_workload_field_content_gitops_repo_url`, point it to the user's own content repo -- not the upstream template.

## Creating a Config

> (RESEARCH NEEDED — RQ-2)

**Current partial guidance:**

Configs live under `ansible/configs/<config-name>/` in your forked repository. At minimum, a config needs a variables defaults file and playbooks that correspond to the lifecycle operations. See the **agnosticd-refactor** skill, audit area 2, for the full checklist once research is complete.

---

## Creating a Workload Role

> (RESEARCH NEEDED — RQ-3)

**Current partial guidance:**

- All custom workload roles must follow the `ocp4_workload_*` naming convention
- All role variables must be prefixed with the full role name to avoid variable collisions across workloads
- Roles live under `ansible/roles/` in your forked repository
- See the upstream `ocp4_workload_example` role as the canonical starting point

---

## Key Commands

All commands take three parameters: `--guid | -g`, `--config | -c`, `--account | -a`.

```bash
# Initial setup (run once from agnosticd-v2/)
./bin/agd setup

# Provision an environment
./bin/agd provision -g myocp -c openshift-cluster -a sandbox1234

# Destroy an environment
./bin/agd destroy -g myocp -c openshift-cluster -a sandbox1234

# Stop / Start / Status
./bin/agd stop -g myocp -c openshift-cluster -a sandbox1234
./bin/agd start -g myocp -c openshift-cluster -a sandbox1234
./bin/agd status -g myocp -c openshift-cluster -a sandbox1234
```

> (RESEARCH NEEDED — RQ-5)

**Current partial guidance:** Stop, start, and status operations are required for RHDP cost management — configs that do not implement them cannot be cost-controlled on the platform and will not be accepted for catalog submission. See the **agnosticd-refactor** skill, audit area 5, for the verification checklist.

## Independent Deployment Scripts

See [references/deployment-scripts.md](references/deployment-scripts.md) for complete deploy/teardown/stop/start script templates with multi-student support, parallel execution, and RHACM hub-and-spoke workload role scaffolding.

---

## Platform Prerequisites

Before running any `agd` command, verify the three requirements below. If a check fails, follow the corrective action for your platform.

### 1. Python 3.12 or higher

```bash
python3 --version    # must return Python 3.12.x or higher
```

If the version is lower than 3.12, install the correct version:

**RHEL 9.5+**
```bash
sudo subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms
sudo dnf -y install git python3.12 python3.12-devel gcc oniguruma-devel
```

**RHEL 10.0+** (ships Python 3.12 as the default `python3`)
```bash
sudo subscription-manager repos --enable codeready-builder-for-rhel-10-$(arch)-rpms
sudo dnf -y install git python3 python3-devel gcc oniguruma-devel
```

**macOS**
```bash
brew install python@3.13
```

### 2. Podman

```bash
podman --version     # must succeed
```

If missing:

**RHEL 9.5+ / 10.0+**
```bash
sudo dnf -y install podman
```

**macOS**
```bash
brew install podman
podman machine init && podman machine start
```

### 3. Virtualenv (created by `agd setup`)

```bash
ls ~/Development/agnosticd-v2-virtualenv/    # must exist
```

If missing, run setup from within the `agnosticd-v2/` directory:
```bash
cd ~/Development/agnosticd-v2
./bin/agd setup
```

## Integration with Field-Sourced Content

AgnosticD provisions the OpenShift clusters that [Field-Sourced Content](https://github.com/rhpds/field-sourced-content-template) deploys onto. The field-sourced-content-template repo ships an AgnosticD workload role (`ocp4_workload_field_content`) that creates an ArgoCD Application to deploy field content on a provisioned cluster.

To deploy field content as an AgnosticD workload, add it to the `workloads:` list in your config variables file:

```yaml
workloads:
  - agnosticd.core_workloads.ocp4_workload_cert_manager
  - ocp4_workload_field_content

ocp4_workload_field_content_gitops_repo_url: "https://github.com/your-org/your-content.git"
```

The workload role uses `openshift_cluster_ingress_domain` and `openshift_api_url` from the provisioned cluster to configure the ArgoCD Application. Field content resources labeled with `demo.redhat.com/userinfo` pass URLs and credentials back to AgnosticD and the RHDP catalog.

For lab guides, add `ocp4_workload_showroom` to `infra_workloads:` to deploy Showroom alongside the cluster. See the **showroom** skill for content authoring and terminal configuration.

See the **field-sourced-content** skill for guidance on authoring the content repository itself (Helm or Ansible patterns).

## Reporting Deployment Info

Every config that deploys to RHDP must surface structured data back to the platform so students see their credentials and URLs in the catalog item. This is done via the `agnosticd_user_info` Ansible action plugin.

**Conceptual data flow:**

```
agnosticd_user_info calls (in workload roles or post-provision tasks)
  │
  ├─→ RHDP catalog  ──────────→ student display (URLs, credentials)
  │
  └─→ Showroom antora.yml     → {openshift_cluster_ingress_domain} and
      attribute injection        other dynamic values in lab content
```

> (RESEARCH NEEDED — RQ-4)

**Current partial guidance:**

- Call `agnosticd_user_info` in the post-provision phase of each workload role that produces a student-facing URL or credential
- The RHDP catalog picks up this data and displays it in the "My Services" page
- Showroom uses the same data to populate `antora.yml` attributes — so lab content that references `{openshift_cluster_ingress_domain}` gets the actual cluster domain at build time
- Every RHDP config must call this module; configs that do not surface output cannot be accepted for catalog submission
- See the **agnosticd-refactor** skill, audit area 4, for the full verification checklist

---

## Best Practices

- Use execution environments for reproducible deployments — `(RESEARCH NEEDED — RQ-6)`
- Use `agnosticd_user_info` to output deployment information (see **Reporting Deployment Info** section above)
- All tasks and plays must have `name:` fields; use YAML literal notation — no `foo=bar` inline syntax
- Follow the git style guide in `references/` for branch naming and PR titles
- Test configs locally before pushing

## Troubleshooting

When `agd provision` or `agd destroy` fails, follow this decision tree:

```
Deployment fails
├─ "agd setup" not run or broken?
│   → Run ./bin/agd setup
│   → Verify Python 3.12+ and podman are installed
│   → Check that agnosticd-v2-virtualenv/ exists
│
├─ Credential / account error?
│   → Check agnosticd-v2-secrets/ for the account file
│   → Verify cloud credentials are valid (AWS STS, Azure token, etc.)
│   → Confirm the account name in -a flag matches a secrets file
│
├─ Cluster unreachable after provisioning?
│   → Run: agd status -g <GUID> -c <CONFIG> -a <ACCOUNT>
│   → Check VPN/network connectivity
│   → Verify openshift_cluster_ingress_domain resolves
│   → Check cloud console for instance/cluster state
│
├─ Workload fails (ocp4_workload_* role)?
│   → Check output in agnosticd-v2-output/<GUID>/
│   → Look for the failing role name in the Ansible output
│   ├─ ocp4_workload_field_content?
│   │   → Verify ocp4_workload_field_content_gitops_repo_url is correct
│   │   → Check ArgoCD Application sync status: oc get app -n openshift-gitops
│   ├─ ocp4_workload_showroom?
│   │   → Verify content_git_repo URL and ref
│   │   → Check showroom pod: oc get pods -n showroom-<GUID>
│   │   → Check showroom pod logs: oc logs -n showroom-<GUID> -l app=showroom
│   └─ Other workload?
│       → Check the role's defaults/main.yml for required variables
│       → Verify operator prerequisites are met (oc get csv -A)
│
├─ Environment deployed but not working for students?
│   → Use the student-readiness skill to run end-to-end checks
│
└─ Still stuck?
    → Use /health:deployment-validator from the RHDP Skills Marketplace
      to generate Ansible validation roles
    → See: https://rhpds.github.io/rhdp-skills-marketplace/
```

## Validation

After a successful deployment, verify the environment before handing it to students:

- **Student readiness**: Use the **student-readiness** skill to verify cluster access, Showroom, terminal, operators, RBAC, and workload resources
- **Module testing**: Use the **workshop-tester** skill to execute each module's exercises against the live environment and classify any failures as Instruction Fix, Infra / Deployment Fix, or Rethink
- **Content quality**: Use `/showroom:verify-content` from the [RHDP Skills Marketplace](https://rhpds.github.io/rhdp-skills-marketplace/) to validate lab content against Red Hat standards
- **Infrastructure health**: Use `/health:deployment-validator` to create Ansible roles that verify pods, routes, and operators