Antora Kubernetes Operations Quick Reference

This quick reference covers common commands and configurations for operating Antora documentation sites deployed on Kubernetes.

Common Commands

Deployment

# Deploy everything
make deploy
# OR
./scripts/deploy.sh

# Validate manifests before deploying
make validate

# Delete deployment (keeps namespace)
make delete

# Delete everything including namespace
make delete-all

Monitoring

# Check status
make status

# View NGINX logs (live)
make logs-nginx

# View Antora init container logs
make logs-init

# Show recent events
make events

# Describe deployment
make describe

Updating Content

# Restart deployment to regenerate content from Git
make restart

# OR manually
kubectl rollout restart deployment/<deployment-name> -n <namespace>

Accessing the Site

# Port forward to local machine
make port-forward
# Then visit: http://localhost:8080

# Get service URLs
make get-url

Troubleshooting

# Open shell in NGINX container
make shell

# Check generated content
make check-content

# Describe pod (shows events and status)
make describe-pod

Configuration Updates

# Update Antora playbook and restart
make update-playbook

# Update NGINX config and restart
make update-nginx-config

File Locations in Containers

Init Container (antora-build)

Path Purpose

/antora/playbook/antora-playbook.yml

Antora playbook configuration

/antora/build/site/

Generated site output

NGINX Container

Path Purpose

/usr/share/nginx/html/

Content root (from shared volume)

/etc/nginx/conf.d/default.conf

NGINX configuration

stdout/stderr

Logs (captured by kubectl logs)

Project Directory Structure

A typical Antora Kubernetes deployment project:

project-root/
├── k8s/                        # Kubernetes manifests
│   ├── deployment.yaml         # Main deployment manifest
│   ├── service.yaml            # Service definition
│   ├── ingress.yaml            # Ingress (optional)
│   ├── *-configmap.yaml        # ConfigMaps
│   └── *-secret.yaml           # Secret references
├── scripts/
│   ├── deploy.sh               # Deployment script
│   └── create-ssh-key.sh       # SSH key generation
├── docs/                       # Documentation content (if co-located)
├── Makefile                    # Common tasks
└── antora-playbook.yml         # Antora configuration

Antora Playbook Key Settings

site:
  title: Your Site Title
  url: https://your-domain.com
  start_page: component::index.adoc

content:
  sources:
    - url: https://github.com/user/repo.git
      branches: main
      start_path: docs

ui:
  bundle:
    url: <ui-bundle-url>

output:
  dir: /antora/build/site

NGINX Configuration Highlights

Setting Value

Port

80 (container) / 8080 (non-privileged alternative)

Root

/usr/share/nginx/html

Gzip

Enabled for text content

Cache

1 year for static assets, no-cache for HTML

Health endpoint

/health

Documentation Repository Structure

Your documentation repository should follow the Antora standard structure:

your-repo/
└── docs/                    # This is the start_path
    ├── antora.yml          # Component descriptor
    └── modules/
        └── ROOT/
            ├── nav.adoc    # Navigation
            └── pages/
                └── *.adoc  # Your content

Content Update Workflow

  1. Edit AsciiDoc files in your Git repository

  2. Commit and push to Git

  3. Run make restart to redeploy (or wait for scheduled rebuild)

  4. Pods recreate → Init container runs → Fetches from Git → Generates site

  5. NGINX serves updated content

Health Checks

The deployment includes health probes:

Probe Endpoint Port

Liveness

/

80

Readiness

/

80

Custom health

/health

80

Resource Recommendations

Init Container (antora-build)

Resource Requests Limits

Memory

256Mi

512Mi - 1Gi

CPU

250m

500m
Increase limits for large documentation sites with many pages or diagram rendering.

NGINX Container

Resource Requests Limits

Memory

64Mi

128Mi

CPU

100m

200m

Scaling

# Manual scaling
kubectl scale deployment/<deployment-name> --replicas=5 -n <namespace>

# Check current replicas
kubectl get deployment/<deployment-name> -n <namespace>

For automatic scaling, configure a Horizontal Pod Autoscaler (HPA).

Security Notes

  • NGINX runs as non-root user

  • Volumes mounted read-only where possible

  • No embedded secrets (use Kubernetes Secrets)

  • Consider Pod Security Standards for production

  • Use fine-grained tokens with minimal permissions

External Resources