Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

describe user workflow in README #95

Merged
merged 2 commits into from
Jan 30, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 145 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,151 @@ app, making it easier to assure stakeholders of your app's security.
Nunki provides an Initializer that handles the remote attestation on the workload side transparently and
fetches the workload certificate. The Initializer runs as init container before your workload is started.

## Generic Workflow

### Prerequisites

* An empty workspace directory.
* The `nunki` binary.
<!-- TODO: from where? -->

```sh
WORKSPACE=$(mktemp -d)
cd "$WORKSPACE"
curl -Lo nunki https://...
```

### Kubernetes Resources

All Kubernetes resources that should be running in confidential containers must be present in the
resources directory. You can generate them from a Helm chart or from a Kustomization, or just copy
them over from your repository.

```sh
mkdir resources
kustomize build $MY_RESOURCE_DIR >resources/all.yaml
# or
helm template release-name chart-name >resources/all.yaml
# or
cp $MY_RESOURCE_DIR/*.yaml resources/
```

All pod definitions and templates in the resources need an additional init container that talks to
the coordinator. Furthermore, the runtime class needs to be set to `kata-cc-isolation` so that the
workloads are started as confidential containers.

```yaml
spec: # v1.PodSpec
runtimeClassName: kata-cc-isolation
initContainers:
- name: initializer
image: "ghcr.io/edgelesssys/nunki/initializer:latest"
env:
- name: COORDINATOR_HOST
value: coordinator
volumeMounts:
- name: tls-certs
mountPath: /tls-config
volumes:
- name: tls-certs
emptyDir: {}
```

Finally, you will need to deploy the Nunki coordinator, too. Start with the following definition
in `resources/coordinator.yaml` and adjust it as you see fit (e.g. labels, namespace, service attributes).

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: coordinator
spec:
selector:
matchLabels:
app.kubernetes.io/name: coordinator
replicas: 1
template:
metadata:
labels:
app.kubernetes.io/name: coordinator
spec:
runtimeClassName: kata-cc-isolation
containers:
- name: coordinator
image: "ghcr.io/edgelesssys/nunki/coordinator:latest"
---
apiVersion: v1
kind: Service
metadata:
name: coordinator
spec:
ports:
- name: intercom
port: 7777
protocol: TCP
- name: coordapi
port: 1313
protocol: TCP
selector:
app.kubernetes.io/name: coordinator
```

### Generate Policies and Manifest

Generate the runtime policy from the resource definitions, attach it to the resources as
annotation and write the coordinator manifest.

```sh
./nunki generate -m manifest.json resources/*.yaml
```

### Apply Resources

Apply the resources to the cluster. Your workloads will block in the initialization phase until a
manifest is set at the coordinator.

```sh
kubectl apply -f resources/
```

### Connect to the Coordinator

For the next steps, we will need to connect to the coordinator. If you did not expose the
coordinator with an external Kubernetes LoadBalancer, you can expose it locally:

```sh
kubectl port-forward service/coordinator 1313:coordapi &
```

### Set Manifest

Attest the coordinator and set the manifest. After this step, the coordinator should start issuing
TLS certs to the workloads, which should now leave the initialization phase.

```sh
./nunki set -c localhost:1313 -m manifest.json
```

### Verify the Coordinator

An end user can verify the Nunki deployment without an explicit list of resources by calling the
coordinator's verification RPC over attested TLS. After successful validation, the output directory
`verify/` will be populated with the TLS root certificates for the configured manifest.

```sh
./nunki verify -c localhost:1313 -o ./verify
```

### Communicate with Workloads

Connect to the workloads using the coordinator's mesh root as a trusted CA certificate.
For example, with `curl`:

```sh
kubectl port-forward service/$MY_SERVICE 8443:$MY_PORT &
curl --cacert ./verify/mesh-root.pem https://localhost:8443
```

## Contributing

See the [contributing guide](CONTRIBUTING.md).
Loading