osmos-infra/README.md

# OSMOS Infrastructure

This repository contains infrastructure configurations for the OSMOS platform, managed via ArgoCD GitOps.

## Repository Structure

```
osmos-infra/
├── README.md
├── argocd-apps/
│   └── environment-provisioner.yaml    # ArgoCD App for provisioner
└── environment-provisioner/
    ├── workflow-template.yaml          # Argo Workflows WorkflowTemplate
    ├── workflow-rbac.yaml              # ClusterRole for workflow execution
    ├── backstage-rbac.yaml             # ClusterRole for Backstage
    └── external-secrets.yaml           # ExternalSecret for GCP Secret Manager
```

## Environment Provisioner

The environment provisioner is an Argo Workflows WorkflowTemplate that creates isolated test environments on-demand via Backstage.

### Features

- **Self-service environments**: Users can create test environments via Backstage UI
- **GitOps-based**: Each environment gets its own Git repository with manifests
- **ArgoCD managed**: Environments are synced and managed by ArgoCD
- **Isolated namespaces**: Each environment is isolated with NetworkPolicies
- **Automatic cleanup**: TTL-based cleanup (configurable)

### Prerequisites

1. **External Secrets Operator** installed with GCP Secret Manager provider
2. **ClusterSecretStore** `gcpsm-secret-store` configured
3. **ArgoCD** installed in `argocd` namespace
4. **Argo Workflows** installed in `argo` namespace
5. **Gitea** accessible for environment repositories

### GCP Secret Manager Secrets Required

Create these secrets in GCP Secret Manager before deployment:

| Secret Name | Description |
|-------------|-------------|
| `gitea-url` | Gitea server URL (e.g., `https://gitea.os-tf-qa.onlinesales.ai`) |
| `gitea-username` | Gitea admin username |
| `gitea-password` | Gitea admin password |
| `argocd-server` | ArgoCD server address (e.g., `argocd.os-tf-qa.onlinesales.ai:443`) |
| `argocd-username` | ArgoCD admin username |
| `argocd-password` | ArgoCD admin password |
| `argo-workflows-token` | Long-lived token for Argo Workflows API |

### Deployment

1. **Create GCP Secret Manager secrets** (if not already created):
   ```bash
   # Using gcloud CLI
   gcloud secrets create gitea-url --data-file=- <<< "https://gitea.os-tf-qa.onlinesales.ai"
   gcloud secrets create gitea-username --data-file=- <<< "giteaAdmin"
   gcloud secrets create gitea-password --data-file=- <<< "<password>"
   gcloud secrets create argocd-server --data-file=- <<< "argocd.os-tf-qa.onlinesales.ai:443"
   gcloud secrets create argocd-username --data-file=- <<< "admin"
   gcloud secrets create argocd-password --data-file=- <<< "<password>"

   # Generate Argo Workflows token and store it
   ARGO_TOKEN=$(kubectl create token argo-server -n argo --duration=999999h)
   gcloud secrets create argo-workflows-token --data-file=- <<< "$ARGO_TOKEN"
   ```

2. **Create repository** in Gitea:
   ```bash
   # Create osmos-infra repository in Gitea via UI or API
   ```

3. **Push this repository** to Gitea:
   ```bash
   git remote add origin https://gitea.os-tf-qa.onlinesales.ai/giteaAdmin/osmos-infra.git
   git push -u origin main
   ```

4. **Verify ClusterSecretStore exists**:
   ```bash
   kubectl get clustersecretstore gcpsm-secret-store
   ```

5. **Apply ArgoCD Application**:
   ```bash
   kubectl apply -f argocd-apps/environment-provisioner.yaml
   ```

6. **Verify deployment**:
   ```bash
   # Check ExternalSecrets synced successfully
   kubectl get externalsecret -n argo
   kubectl get externalsecret -n backstage

   # Check secrets were created
   kubectl get secret gitea-credentials argocd-credentials -n argo
   kubectl get secret argo-workflows-token -n backstage

   # Check WorkflowTemplate
   kubectl get workflowtemplate -n argo

   # Check RBAC
   kubectl get clusterrole workflow-executor backstage-environment-manager
   ```

### Usage

Once deployed, environments can be created via:
1. **Backstage UI**: Navigate to the Environments page and click "Create Environment"
2. **Direct API**: Submit a workflow with the required parameters

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    ArgoCD (GitOps)                               │
├─────────────────────────────────────────────────────────────────┤
│  App: environment-provisioner-infra                              │
│  ├── WorkflowTemplate (environment-provisioner)                  │
│  ├── ClusterRole (workflow-executor)                             │
│  ├── ClusterRoleBinding (workflow-executor-binding)              │
│  ├── ClusterRole (backstage-environment-manager)                 │
│  ├── ClusterRoleBinding (backstage-environment-manager-binding)  │
│  └── ExternalSecrets (gitea-credentials, argocd-credentials)     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Argo Workflows                                │
├─────────────────────────────────────────────────────────────────┤
│  WorkflowTemplate: environment-provisioner                       │
│  ├── Step 1: create-repo (creates Gitea repo with manifests)    │
│  ├── Step 2: create-argo-app (creates ArgoCD Application)       │
│  └── Step 3: register-hades-ips (optional health registration)  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Per-Environment                               │
├─────────────────────────────────────────────────────────────────┤
│  Gitea Repo: environment-{namespace}                             │
│  └── manifests/                                                  │
│      ├── namespace.yaml                                          │
│      ├── networkpolicy.yaml                                      │
│      └── {service}-application.yaml (ArgoCD App per service)     │
└─────────────────────────────────────────────────────────────────┘
```

### Security

- **Secrets**: All credentials are stored in GCP Secret Manager and synced via External Secrets Operator
- **RBAC**: Minimal permissions granted to workflow and backstage service accounts
- **TLS**: All connections use TLS in production
- **Network Isolation**: Each environment is isolated via NetworkPolicies

### Troubleshooting

**ExternalSecret not syncing:**
```bash
kubectl describe externalsecret gitea-credentials -n argo
```

**WorkflowTemplate not found:**
```bash
kubectl get workflowtemplate -n argo
kubectl describe workflowtemplate environment-provisioner -n argo
```

**Permission denied errors:**
```bash
kubectl auth can-i create namespaces --as=system:serviceaccount:argo:argo
```