Create ansible-container-deploy.md via n8n
This commit is contained in:
parent
a87426a7a2
commit
aa32454aef
211
Tech/Projects/ansible-container-deploy.md
Normal file
211
Tech/Projects/ansible-container-deploy.md
Normal file
@ -0,0 +1,211 @@
|
||||
---
|
||||
project: ansible-container-deploy
|
||||
type: project-plan
|
||||
status: active
|
||||
path: Tech/Projects
|
||||
tags:
|
||||
- pbs
|
||||
- ansible
|
||||
- docker
|
||||
- deployment
|
||||
- automation
|
||||
created: 2026-04-25
|
||||
updated: 2026-04-25
|
||||
---
|
||||
# Ansible Container Deploy
|
||||
|
||||
Tag-based per-container Ansible deployment, CLI wizard enhancements, and
|
||||
GitHub clone integration for the PBS Docker stack.
|
||||
|
||||
## Background
|
||||
|
||||
The wordpress-install repo (pbs-production/) has been refactored from a
|
||||
loop-based all-or-nothing Docker deployment to a tag-based `import_tasks`
|
||||
pattern. Each container has its own task wrapper under `tasks/containers/`
|
||||
that calls `common/deploy.yml` with container-specific variables. The
|
||||
docker-container repo (pbs-workshop/) houses a CLI wizard that scaffolds
|
||||
new container files (compose template, task wrapper, env template) but
|
||||
currently only generates simple-tier containers.
|
||||
|
||||
The tag-based refactor is coded but untested. The wizard needs enhancements
|
||||
to support medium and complex tier containers. A separate GitHub deploy
|
||||
refactor (github-deploy-refactor, status: complete) established the
|
||||
pbsdeploybot machine user pattern for repo cloning — that logic needs to be
|
||||
absorbed into the dockers role.
|
||||
|
||||
## Repos
|
||||
|
||||
- **wordpress-install (pbs-production/)** — production deployment repo,
|
||||
tag-based structure in place
|
||||
- **docker-container (pbs-workshop/)** — tooling repo, CLI wizard and
|
||||
scaffolding
|
||||
- **claude-code-scaffolding-skill** — separate project, consumes the
|
||||
patterns defined here (see Phase 5)
|
||||
|
||||
## Architecture
|
||||
|
||||
### common/deploy.yml Variable Contract
|
||||
|
||||
Required:
|
||||
- `container_name` (str) — directory name under `files/` and deploy path at
|
||||
`{{ dockers_path }}//`
|
||||
|
||||
Optional:
|
||||
- `container_has_env` (bool, default false) — templates
|
||||
`files//.env.j2` → `.env`
|
||||
- `container_extra_dirs` (list of str) — additional directories to create
|
||||
- `container_extra_files` (list of {src, dest, mode}) — static files to copy
|
||||
- `container_extra_templates` (list of {src, dest, mode}) — Jinja templates
|
||||
to render
|
||||
|
||||
Global vars (from vars/main.yml and inventory):
|
||||
- `dockers_path` — base directory (`/opt/docker`)
|
||||
- `user` — system user for file ownership
|
||||
- `dockers_lan_name` — Docker network name
|
||||
- `dockers_domain_name` — primary domain
|
||||
|
||||
### Container Complexity Tiers
|
||||
|
||||
**Simple** (redis, portainer, uptime-kuma): `container_name` only
|
||||
**Medium** (pbs-api): adds `container_extra_dirs`, `container_extra_files`,
|
||||
`container_extra_templates`
|
||||
**Complex** (wordpress): medium plus post-deploy tasks
|
||||
|
||||
### common/github.yml (planned)
|
||||
|
||||
Will sit alongside `common/deploy.yml`. Containers that build from a cloned
|
||||
repo import `github.yml` first (clone/pull via pbsdeploybot), then
|
||||
`deploy.yml` (compose up). Uses the same SSH host alias pattern established
|
||||
in github-deploy-refactor.
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 1: Validate Tag-Based Deployment
|
||||
|
||||
Test the existing tag-based refactor on staging.
|
||||
|
||||
- [ ] Run `--tags traefik` against staging, verify only traefik deploys
|
||||
- [ ] Run `--tags wordpress` against staging, verify only wordpress deploys
|
||||
- [ ] Run `--tags "traefik,wordpress"` to verify multi-tag targeting
|
||||
- [ ] Run `--skip-tags n8n` to verify exclusion works
|
||||
- [ ] Run full playbook (no tags) to verify all-container deployment still
|
||||
works
|
||||
- [ ] Document any issues or adjustments needed
|
||||
|
||||
### Phase 2: Absorb GitHub Clone Logic
|
||||
|
||||
Migrate the github role's clone logic into the dockers role as
|
||||
`common/github.yml`.
|
||||
|
||||
- [ ] Create `tasks/common/github.yml` in the dockers role
|
||||
- [ ] Accept per-invocation vars: `repo_url`, `repo_dest`, `repo_version`
|
||||
- [ ] Use `become_user: "{{ ansible_user }}"` for SSH config access
|
||||
- [ ] Default `repo_version` to `main`
|
||||
- [ ] Update container task wrappers that need repo clones (e.g., pbs-hub)
|
||||
to import `github.yml` before `deploy.yml`
|
||||
- [ ] Test on staging with an existing repo-based container
|
||||
- [ ] Decide whether standalone github role is kept for non-container use
|
||||
cases or retired entirely
|
||||
|
||||
### Phase 3: Wizard Enhancements
|
||||
|
||||
Extend the CLI wizard to support medium-tier containers and repo-based
|
||||
builds.
|
||||
|
||||
#### 3a: Dockerfile Support
|
||||
- [ ] Add wizard prompt: "Does this container need a custom Dockerfile?"
|
||||
- [ ] If yes, generate a Dockerfile template in the container's files
|
||||
directory
|
||||
- [ ] Add Dockerfile to `container_extra_files` in the generated task
|
||||
wrapper
|
||||
|
||||
#### 3b: Git Repo Support
|
||||
- [ ] Add wizard prompt: "Is this container built from a git repo?"
|
||||
- [ ] If yes, prompt for `repo_url` and `repo_version`
|
||||
- [ ] Generate task wrapper that imports `common/github.yml` before
|
||||
`common/deploy.yml`
|
||||
|
||||
#### 3c: Extra Files/Dirs/Templates
|
||||
- [ ] Add wizard prompts for additional directories, static files, and
|
||||
templates
|
||||
- [ ] Generate `container_extra_dirs`, `container_extra_files`,
|
||||
`container_extra_templates` entries in the task wrapper
|
||||
|
||||
#### 3d: Vault Secret References
|
||||
- [ ] When the wizard detects vars that need secrets (db passwords, API
|
||||
keys, etc.), generate placeholder references in compose templates using `{{
|
||||
vault_ }}` syntax
|
||||
- [ ] Output a post-scaffold checklist reminding the user which vault vars
|
||||
need to be manually added to encrypted group vars
|
||||
|
||||
#### 3e: Repo-Context Awareness
|
||||
- [ ] When the wizard is run inside the production repo, it should read
|
||||
existing `vars/main.yml`, network configs, and Traefik patterns to inform
|
||||
prompts and output
|
||||
- [ ] Wizard should auto-detect available networks, domain name, and base
|
||||
path from existing config
|
||||
- [ ] Wizard should append generated vars entries to `vars/main.yml` (or
|
||||
output them for manual paste)
|
||||
- [ ] Implementation details deferred to Claude Code — requirement is
|
||||
stated, approach is flexible
|
||||
|
||||
### Phase 4: Production Rollout
|
||||
|
||||
- [ ] Deploy tag-based structure to production (after staging validation)
|
||||
- [ ] Test selective deployment on production with a low-risk container
|
||||
- [ ] Update any runbooks or deployment docs
|
||||
|
||||
### Phase 5: Scaffolding Skill Integration
|
||||
|
||||
Separate project (claude-code-scaffolding-skill), documented here for
|
||||
dependency tracking.
|
||||
|
||||
Three new scaffold types to add:
|
||||
- **`ansible-docker-container`** — scaffolds the project structure for a
|
||||
tag-based Docker container deployment (folder tree, template files, vars
|
||||
skeleton). The wizard then fills in the details.
|
||||
- **`ansible-role`** — reusable Galaxy-style role (defaults, handlers,
|
||||
meta, tasks, templates, Molecule testing)
|
||||
- **`ansible`** — full playbook project (ansible.cfg, inventory,
|
||||
group_vars, host_vars, playbooks, roles, requirements.yml, vault setup)
|
||||
|
||||
The scaffold creates project structure; the wizard populates
|
||||
container-specific content. Scaffold = one-time project start, wizard =
|
||||
repeated container additions.
|
||||
|
||||
This project provides the reference patterns. The scaffolding skill project
|
||||
owns implementation.
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **Wizard vs scaffold split:** Scaffold generates project structure,
|
||||
wizard fills in container details. Different tools, same conventions.
|
||||
- **Vault secrets stay manual:** Wizard generates `{{ vault_* }}`
|
||||
placeholder references and a reminder checklist. Actual vault entries are
|
||||
hand-added.
|
||||
- **Context-aware wizard implementation deferred to Claude Code:**
|
||||
Requirement is that the wizard reads existing repo config when run
|
||||
in-place. How it does that is an implementation detail.
|
||||
- **Scaffolding skill: start inside existing skill, separate if it doesn't
|
||||
fit.** Build assuming merge into claude-code-scaffolding-skill. If
|
||||
infrastructure types feel forced next to dev tooling types, split into
|
||||
standalone skill.
|
||||
- **common/github.yml pattern:** Clone logic absorbed into dockers role,
|
||||
not kept as a standalone role for container use cases. Matches the
|
||||
common/deploy.yml pattern.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- github-deploy-refactor (complete) — provides pbsdeploybot auth pattern
|
||||
- claude-code-scaffolding-skill (separate project) — consumes patterns from
|
||||
Phase 3+
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should the standalone github role be kept for non-container clone use
|
||||
cases, or is pbsdeploybot + common/github.yml sufficient for everything?
|
||||
- Final call on scaffolding skill merge vs standalone — deferred until
|
||||
implementation reveals fit
|
||||
|
||||
|
||||
...sent from Jenny & Travis
|
||||
Loading…
Reference in New Issue
Block a user