Add Your Own Package (Optional)

This tutorial walks through packaging a sample application and deploying it alongside UDS Core. By the end you’ll have an app exposed through Istio ingress and protected by Keycloak SSO, wired up automatically by the UDS Operator.

The sample app is podinfo, a lightweight Go service with a Helm chart.

Note

Assumes you have completed Install and Deploy UDS and have a running local cluster.

---

Requirements

• UDS CLI — installed in the previous step (includes Zarf via uds zarf)

---

Create the Zarf Package

A Zarf Package bundles your application’s images and manifests for airgap-safe delivery. The UDS Operator watches for Package custom resources and automatically configures Istio ingress, Keycloak SSO, Prometheus monitoring, and network policies for your app.

1. Create a working directory

   mkdir podinfo-package && cd podinfo-package

2. Create the UDS Package CR

   This manifest tells the UDS Operator what platform integrations your app needs:

   podinfo-package.yaml

   apiVersion: uds.dev/v1alpha1
   kind: Package
   metadata:
     name: podinfo
     namespace: podinfo
   spec:
     network:
       expose:
         - service: podinfo
           selector:
             app.kubernetes.io/name: podinfo
           gateway: tenant
           host: podinfo
           port: 9898
     sso:
       - name: Podinfo SSO
         clientId: uds-core-podinfo
         redirectUris:
           - "https://podinfo.uds.dev/login"
         enableAuthserviceSelector:
           app.kubernetes.io/name: podinfo
         groups:
           anyOf:
             - "/UDS Core/Admin"
     monitor:
       - selector:
           app.kubernetes.io/name: podinfo
         targetPort: 9898
         portName: http
         description: "podinfo metrics"
         kind: PodMonitor

   When the operator reconciles this CR, it will:

   • Create an Istio VirtualService exposing podinfo at podinfo.uds.dev
   • Register a Keycloak OIDC client and protect the app with Authservice
   • Create a Prometheus PodMonitor for metrics scraping
   • Generate all required NetworkPolicy resources automatically

3. Create zarf.yaml

   The Zarf package definition bundles the Helm chart, the Package CR, and the container image together:

   zarf.yaml

   kind: ZarfPackageConfig
   metadata:
     name: podinfo
     version: 0.0.1
   
   components:
     - name: podinfo
       required: true
       charts:
         - name: podinfo
           version: 6.10.1
           namespace: podinfo
           url: https://github.com/stefanprodan/podinfo.git
           gitPath: charts/podinfo
       manifests:
         - name: podinfo-uds-config
           namespace: podinfo
           files:
             - podinfo-package.yaml
       images:
         - ghcr.io/stefanprodan/podinfo:6.10.1

4. Build and deploy the package

   uds zarf package create --confirm
   uds zarf package deploy zarf-package-podinfo-*.tar.zst --confirm

   This builds zarf-package-podinfo-<arch>-0.0.1.tar.zst, then deploys it onto your existing UDS Core cluster. The UDS Operator picks up the Package CR and configures ingress, SSO, monitoring, and network policies automatically.

---

Verify

Check that the UDS Operator processed the Package resource:

kubectl get package -n podinfo

Expected output:

Output

NAME      STATUS   SSO CLIENTS            ENDPOINTS             MONITORS          NETWORK POLICIES   AGE
podinfo   Ready    ["uds-core-podinfo"]   ["podinfo.uds.dev"]   ["podinfo-..."]   9                  2m

Ready confirms all platform integrations were provisioned.

Access the app:

Navigate to https://podinfo.uds.dev. You’ll be redirected to Keycloak. Only members of /UDS Core/Admin can log in.

Create a test user by setting up a simple tasks.yaml file that imports a helper from uds-common:

tasks.yaml

includes:
  - common-setup: https://raw.githubusercontent.com/defenseunicorns/uds-common/main/tasks/setup.yaml

Then run the task:

uds run common-setup:keycloak-user --set KEYCLOAK_USER_GROUP="/UDS Core/Admin"

Danger

Default credentials: username: doug / password: unicorn123!@#UN. These are development-only credentials—never use them in production.

View metrics in Grafana:

Go to https://grafana.admin.uds.dev and navigate to Explore, then Prometheus, and run:

PromQL

rate(process_cpu_seconds_total{namespace="podinfo"}[$__rate_interval])

---

What Happened

By declaring your app’s needs in the Package CR, the UDS Operator automatically provisioned:

• Istio VirtualService and AuthorizationPolicy for ingress
• Keycloak OIDC client with Authservice enforcement
• NetworkPolicy resources scoped to only required traffic
• Prometheus PodMonitor for metrics scraping

For the full Package CR reference, see Package CR.