Research: Minerva Onboarding Process

1. Overview

This page documents the concrete steps required to onboard an application to the Minerva platform. It covers the repositories that need to be touched, the access groups that need to be created, and the deploy tokens / secrets that need to be configured.

The process has two goals:

1. Set up Git repositories for deploying your application to Minerva
2. Grant Minerva access to you and your development team

2. Repository Architecture

Minerva enforces separation of application code from Kubernetes manifests:

Why separate repos:

• Modify manifests without triggering full CI builds
• Cleaner audit log (no development noise in deployment history)
• Multi-repo apps can deploy as a single unit
• Developers building code may not have push access to production configs
• Avoids infinite CI loops from manifest changes

3. Access Setup (CIDM)

Step 1: Create Security Group

Controls access to Minerva management apps (ArgoCD, Grafana, Vault).

1. Go to CIDM  → Group Management → Create Group
2. Select “I will use this group to manage access to applications, file shares, systems, etc.”
3. Name: ROLE-PRED-MINERVA-{PROJECTNAME}-{ENVNAME}

Naming rules (strict):

• Per-environment groups: ROLE-PRED-MINERVA-XRED-ELN-DEV, ...-UAT, ...-PROD
• Single group for all envs: ROLE-PRED-MINERVA-XRED-ELN (omit env suffix)

Even if you are the owner, you must add yourself as a member.

Step 2: Create Cloud Group

Same name as the security group, but type Cloud Group. Controls access to AWS accounts via web console or CLI.

1. Go to CIDM → Cloud Group Management → Create Cloud Group
2. Choose “RCP AWS Identity Central” application
3. Use the same group name as the security group
4. Assign the same members

If “Cloud Group Management” is not visible, request the ‘Cloud Group Management Access’ role in CIDM first.

Step 3: Merge Request in Minerva Project Repository

Register your project by editing projects/list.yaml in the appropriate environment repo:

Required YAML entry:

- name: xred-eln
  istioMtlsPolicy: STRICT
  friendly_name: "xRED ELN Integration Platform"
  product_owner:
    - name: "Owner Name"
      email: owner@roche.com
  business_contact:
    - name: "Business Contact"
      email: business@roche.com
  technical_contact:
    - name: "Tech Contact"
      email: tech@roche.com
  business_case: "Integration platform connecting Signals ELN with internal Roche systems"
  sra_dcr: "XXXX"  # mandatory for PROD
  value_streams: "research_data_access"
  environment: dev
  rbacadmin: false
  netadmin: false
  description: "Middleware layer for Signals ELN integrations on Minerva"
  groups:
    - ROLE-PRED-MINERVA-XRED-ELN-DEV
  namespaces:
    - xred-eln
  repos:
    - https://github.com/roche-innersource/xred-eln-infrastructure.git
  labels:
    minerva.roche.com/project: xred-eln
    minerva.roche.com/service: research_data_access
    minerva.roche.com/environment: dev
  applications:
    - name: xred-eln-demo
      description: "Demo integration"
      namespace: xred-eln
      source:
        path: k8s/demo/
        repoURL: https://github.com/roche-innersource/xred-eln-infrastructure.git
        targetRevision: dev

Key fields:

• istioMtlsPolicy: Use STRICT for production, PERMISSIVE for testing
• sra_dcr: Mandatory for PROD environment
• rbacadmin: Keep false unless you need ClusterRoles (requires Minerva team approval)
• netadmin: Keep false unless you need Istio Sidecars (requires approval)
• labels: Used for AWS cost tracking by CPU/memory

Submit MR to the appropriate branch and assign to the Minerva team member on your JIRA ticket.

4. Deploy Tokens and Secrets

Three tokens need to be created to establish the ArgoCD → infrastructure repo → container registry chain:

4.1 Infrastructure Repository Deploy Token

Allows ArgoCD to pull K8s manifests from the infrastructure repo.

For GitLab:

1. Infrastructure repo → Settings → Repository → Deploy tokens
2. Name the token, select read_repository
3. Store in Vault: create secret repo-secret-xred-eln with keys:
   • url: infrastructure repo URL
   • username: deploy token name
   • password: deploy token password

For GitHub:

1. Create a fine-grained Personal Access Token with Contents: Read permission
2. Associate with a service account (not personal account)
3. Store in Vault with the same key structure

4.2 Application Registry Deploy Token

Allows Minerva to pull Docker images from the container registry.

For GitLab:

1. Application repo → Settings → Repository → Deploy tokens
2. Select read_registry
3. Generate the dockerconfigjson:

GL_USERNAME="<USERNAME>"
GL_TOKEN="<TOKEN>"
AUTH=$(echo -n "$GL_USERNAME:$GL_TOKEN" | base64)
echo '{"auths":{"registry.code.roche.com":{"username":"'$GL_USERNAME'","password":"'$GL_TOKEN'","auth":"'$AUTH'"}}}'

4. Store the output in Vault

For GitHub (GHCR):

1. Create a Personal Access Token Classic (fine-grained tokens don’t work with registries)
2. Select read:packages permission
3. Use ghcr.io as the registry address in the dockerconfigjson
4. Store in Vault

4.3 Merge Secrets to Minerva Project Repository

Create ExternalSecret resources in the projects-secrets/ folder of the Minerva project repo:

Infrastructure repo secret (repo_ext_secret_xred-eln.yaml):

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: repo-xred-eln-ext-secret
  namespace: argocd
spec:
  refreshInterval: 5m
  secretStoreRef:
    name: ss-xred-eln
    kind: SecretStore
  target:
    name: repo-xred-eln-secret
    template:
      metadata:
        labels:
          argocd.argoproj.io/secret-type: repository
  data:
    - secretKey: url
      remoteRef:
        key: <secret-engine>/<path>
        property: url
    - secretKey: username
      remoteRef:
        key: <secret-engine>/<path>
        property: username
    - secretKey: password
      remoteRef:
        key: <secret-engine>/<path>
        property: password

Docker registry secret (externalsecret_docker_registry.yaml):

apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: docker-registry-ext-secret
spec:
  refreshInterval: "1m"
  secretStoreRef:
    name: ss-xred-eln
    kind: SecretStore
  target:
    name: xred-eln-registry-secret
    deletionPolicy: Retain
    template:
      engineVersion: v2
      mergePolicy: Replace
      type: kubernetes.io/dockerconfigjson
  data:
    - secretKey: .dockerconfigjson
      remoteRef:
        key: "<secret-engine>/<path>/registry"
        property: .dockerconfigjson

Add both files to projects-secrets/kustomization.yaml and submit MR.

5. Infrastructure Repository Structure

The infrastructure repo contains the K8s manifests that ArgoCD deploys:

k8s/
├── kustomization.yaml           # Top-level: lists all apps
├── secretstore.yaml             # Vault connection (shared)
├── externalsecret-registry.yaml # Registry credentials (shared)
├── demo/
│   ├── kustomization.yaml
│   ├── deployment-backend.yaml
│   ├── service-backend.yaml
│   └── ingress-backend.yaml
└── my-integration/
    ├── kustomization.yaml
    ├── deployment-backend.yaml
    ├── service-backend.yaml
    ├── ingress-backend.yaml
    └── externalsecret-app.yaml  # App-specific secrets

Deployment requirements

Every deployment must include:

securityContext:
  allowPrivilegeEscalation: false

Ingress configuration

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    cert-manager.io/cluster-issuer: roche-acme-prod
    cert-manager.io/common-name: xred-eln-app.minerva.sandbox.pcloud.roche.com
    external-dns.alpha.kubernetes.io/hostname: xred-eln-app.minerva.sandbox.pcloud.roche.com
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
    nginx.ingress.kubernetes.io/service-upstream: "true"
    nginx.ingress.kubernetes.io/upstream-vhost: app-backend.xred-eln.svc.cluster.local

Hostnames by environment:

When istioMtlsPolicy: STRICT, NGINX ingress must route to a single upstream service so outbound traffic is intercepted by the Istio sidecar.

SSL certificates are automatically generated via cert-manager.io/cluster-issuer.

SecretStore and ExternalSecret

A SecretStore is auto-created for your project when the MR is merged. Reference it as ss-xred-eln in all ExternalSecrets. Key fields:

• path: Secret engine name from Vault
• namespace: Vault namespace used at login
• mountPath: Same as path
• serviceAccountRef: Use default unless you have custom service accounts

6. Application Repository CI Pipeline

Example GitLab CI for building and pushing Docker images:

image: docker:27.5.1
services:
  - docker:27.5.1-dind
before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
stages:
  - build
build:
  tags:
    - linux-amd64-s-sock
  stage: build
  script:
    - docker pull $CI_REGISTRY_IMAGE:latest || true
    - docker build --cache-from $CI_REGISTRY_IMAGE:latest
        --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
        --tag $CI_REGISTRY_IMAGE:latest .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest

For rate-limited registries (e.g. DockerHub), use docker-cache.repository.intranet.roche.com/ as a prefix.

7. Verification

After all MRs are merged:

1. Check ArgoCD for your application status:
   • DEV 
   • UAT 
   • PROD 
2. Verify your app is Healthy and Synced
3. Access your app at https://xred-eln-{app}-api.{domain}/health

8. Onboarding Checklist

9. Post-Onboarding Next Steps

• Monitoring and logging  — Datadog dashboards
• Spot instances  — schedule non-critical workloads on Spot
• Scheduled scaling  — scale down during off-hours
• Node affinity  — run on specific node types
• Security context  — configure pod security
• ArgoCD SyncWaves  — control deployment order