vshell/openshift/README.md

# OpenShift manifests for VShell

Two independent halves:

- **run** (the normal path): pull `att-gitlab.apps.evd.geaerospace.net:5050/att/infrastructure/vshell:latest`
  from the internal ATT GitLab registry and run it in the `vshell` project.
- **build** (optional): build the image inside OpenShift from the private Gitea
  repo, for when you want the cluster to produce the image itself.

All manifests have been decode-tested with `oc create --dry-run=client` against
the OpenShift 4.22 client scheme.

## Run from the internal registry

| File | What it does |
|---|---|
| [`00-namespace.yaml`](00-namespace.yaml) | Project `vshell`. |
| [`cluster/00-insecure-registry.yaml`](cluster/00-insecure-registry.yaml) | Cluster-scoped: mark `att-gitlab.apps.evd.geaerospace.net:5050` insecure (the `-k` equivalent). |
| [`runtime/00-serviceaccount.yaml`](runtime/00-serviceaccount.yaml) | `ServiceAccount/vshell`, carries the pull secret. |
| [`runtime/01-scc.yaml`](runtime/01-scc.yaml) | Least-privilege SCC allowing UID 0 + Role/RoleBinding so only this SA may use it. |
| [`runtime/02-pvc.yaml`](runtime/02-pvc.yaml) | `PersistentVolumeClaim/vshell-data` for config + TLS certificate. |
| [`runtime/03-deployment.yaml`](runtime/03-deployment.yaml) | Deployment pulling from the GitLab registry. |
| [`runtime/04-service.yaml`](runtime/04-service.yaml) | ClusterIP service for ports 22/21/990/80/443. |
| [`runtime/05-route.yaml`](runtime/05-route.yaml) | HTTPS Route, **passthrough** termination. |
| [`runtime/06-att-gitlab-pull-secret.yaml`](runtime/06-att-gitlab-pull-secret.yaml) | Registry credentials (placeholders - create from the CLI). |

```sh
# 1. registry credentials (deploy token / PAT with read_registry)
oc create secret docker-registry att-gitlab-pull -n vshell \
  --docker-server=att-gitlab.apps.evd.geaerospace.net:5050 \
  --docker-username=<user> --docker-password=<token>

# 2. let the nodes pull from it over plain/insecure TLS (cluster-admin; rolls all nodes)
oc apply -f cluster/00-insecure-registry.yaml

# 3. project + workload
oc apply -f 00-namespace.yaml
oc apply -f runtime/
oc get pods,route -n vshell
```

`cluster/00-insecure-registry.yaml` is the pod-world replacement for
`podman pull -k`: a pod spec cannot opt out of TLS verification, so the node CRI
must be told the registry is exempt. Editing `Image/cluster` makes the Machine
Config Operator drain and reboot every node — do it in a maintenance window, and
remember the rollback rolls them again.

If the cluster sets `registrySources.allowedRegistries`, add
`att-gitlab.apps.evd.geaerospace.net:5050` **and** the internal registry
`image-registry.openshift-image-registry.svc:5000` to that list, or other pulls
start failing. If the registry has a private CA, prefer
`spec.additionalTrustedCA` over `insecureRegistries`.

`restricted-v2` forbids UID 0 and VShell needs root (PAM reads `/etc/shadow`,
writes `/var/run/*.pid`, creates root-owned host keys), hence the SCC — or
`oc adm policy add-scc-to-user anyuid -z vshell -n vshell` for the stock one.
The Route is passthrough because `vshell-httpsd` terminates TLS itself with the
PKCS#12 certificate the entrypoint generates; SSH (22), explicit FTPS (21) and
implicit FTPS (990) cannot use a Route, so expose the Service with a
NodePort/LoadBalancer. Never scale the Deployment past one replica: fixed ports
and a single host key.

## Build in OpenShift (optional)

| File | What it does |
|---|---|
| [`01-gitea-source-secret.yaml`](01-gitea-source-secret.yaml) | `kubernetes.io/basic-auth` secret for the private Gitea repo. |
| [`02-vshell-imagestream.yaml`](02-vshell-imagestream.yaml) | Output `ImageStream/vshell` (`latest`). |
| [`03-buildconfig.yaml`](03-buildconfig.yaml) | `BuildConfig/vshell` — Docker strategy, git source, `ubuntu:24.04` base. Can also be pointed at the GitLab registry (see the comments in the file). |
| [`04-base-imagestream.yaml`](04-base-imagestream.yaml) | Optional: keep the Ubuntu base inside the cluster instead of pulling Docker Hub each build. |
| [`05-dockerhub-pull-secret.yaml`](05-dockerhub-pull-secret.yaml) | Optional: Docker Hub credentials so base pulls are not rate limited. |

```sh
oc apply -f 00-namespace.yaml
oc create secret generic gitea-vshell-source -n vshell \
  --type=kubernetes.io/basic-auth \
  --from-literal=username=mward4 \
  --from-literal=password=<gitea-token>
oc apply -f 02-vshell-imagestream.yaml -f 03-buildconfig.yaml
oc start-build vshell -n vshell --follow
```

The repository vendors the vendor `.deb`, so a build pod needs egress only to
`gitea.milesward.dev`, `registry-1.docker.io` and `archive.ubuntu.com`. For
air-gapped clusters import `ubuntu:24.04` with `04-base-imagestream.yaml`, point
`strategy.dockerStrategy.from` at `ImageStreamTag ubuntu:24.04`, and add an
internal apt mirror.

## Caveats

- Builds run as root inside the build pod by default, which the Dockerfile's
  `apt-get` and `dpkg -i` need. Unprivileged builds (`BUILD_PRIVILEGED=false`)
  are an opt-in Developer Preview feature and would break this Dockerfile.
- VShell runs under its 60-day evaluation license (expires 2026-12-04) until a
  license file is mounted and `LicenseFilePath` is set.
- The image and repository are private because VShell is commercial software
  distributed under the VanDyke Software EULA.