Install with Canonical Identity Platform using Terraform¶

This guide describes how to install Charmed Kubeflow (CKF) integrated with the Canonical Identity Platform using Terraform.

This solution runs CKF on the Istio Ambient Mesh and integrates it with the Canonical Identity Platform (Hydra, Kratos and the Login UI) so that authentication is handled by the Identity Platform.

Note

This integration is available in Istio ambient mode only.

The deployment spans four Juju models:

istio-system: the Istio ambient control plane (istio-k8s).
iam: the Canonical Identity Platform bundle (Hydra, Kratos and the Login UI).
iam-core: the Identity Platform dependencies (postgresql-k8s, traefik and self-signed-certificates).
kubeflow: the CKF applications, the two ambient ingress gateways (UI and machine-to-machine) and the Identity Platform authentication charms.

Requirements¶

A Kubernetes (K8s) cluster that:
- uses a version supported by Charmed Kubeflow (see Supported versions), with a default storage class configured.
- has a load balancer provider, so that the ingress gateways and the Identity Platform can be exposed through LoadBalancer services. For example, MetalLB on MicroK8s.
- meets the Istio platform prerequisites for the ambient mesh.
Terraform CLI. You can install it using the snap.
kubectl configured to access your cluster.

Bootstrap Juju¶

CKF is deployed to Kubernetes with Juju. Before deployment, a Juju controller must be bootstrapped to the K8s cluster. See Get started with Juju for more details.

Note

Check Supported versions for version compatibility between CKF, Juju and K8s.

Deploy CKF with the Identity Platform¶

Deploy the solution as follows:

Clone the charmed-kubeflow-solutions repository and change directory to the solution module:

git clone https://github.com/canonical/charmed-kubeflow-solutions
cd charmed-kubeflow-solutions
git checkout main
cd terraform/tests/kubeflow-ambient-iam

Initialise Terraform. The following command downloads all the required Terraform modules and installs the Terraform Juju provider:

terraform init

Create a Git repository for the Profile Management Representation (PMR).

The github-profiles-automator charm keeps the Kubeflow profiles in sync with a YAML file (the PMR) stored in a GitHub repository. Create an empty repository (for example, https://github.com/example-org/kubeflow-pmr). You add the PMR file to it later, in the Prepare the PMR section, once you have created a user to own the profiles.

Configure the github-profiles-automator charm to sync from your PMR repository by creating a terraform.tfvars file in the current directory:

# github-profiles-automator: sync Kubeflow profiles from this PMR repository.
github_profiles_automator_config = {
  repository = "https://github.com/example-org/kubeflow-pmr.git"
}

Note

Terraform automatically loads terraform.tfvars during terraform apply.

By default, the github-profiles-automator charm reads a file named pmr.yaml at the repository root. To use a different file or path, set pmr-yaml-path in github_profiles_automator_config.

Deploy the solution using Terraform, setting the external hostnames for the ingress gateways and the Identity Platform:

terraform apply \
   -var external_ui_hostname="ui.kubeflow.com" \
   -var external_m2m_hostname="api.kubeflow.com" \
   -var external_auth_hostname="auth.kubeflow.com"

Note

These hostnames do not need to be registered with a public DNS provider. You make them resolvable in the Configure DNS for the ingress gateways section below.

The command above:

Creates four Juju models: istio-system, iam, iam-core and kubeflow.
Deploys the Istio ambient control plane into istio-system.
Deploys the Canonical Identity Platform bundle into iam and its dependencies (including traefik) into iam-core.
Deploys CKF with the two ambient ingress gateways and the Identity Platform authentication charms into kubeflow.
Deploys the github-profiles-automator charm, which syncs Kubeflow profiles from your PMR repository.
Sets the external hostname on the UI gateway (ui.kubeflow.com), the machine-to-machine gateway (api.kubeflow.com) and the Identity Platform ingress (auth.kubeflow.com).

See kubeflow-ambient-iam deployment for more details.

Verify all charms are in active status by monitoring the Juju models:

juju status -m istio-system --watch 1s
juju status -m iam --watch 1s
juju status -m iam-core --watch 1s
juju status -m kubeflow --watch 1s

Note

Deployment may take several minutes to complete, depending on the cluster’s node specifications.

Note

The github-profiles-automator charm remains in a blocked state until you add the PMR file to the repository, which you do in the Prepare the PMR section.

Configure DNS for the ingress gateways¶

The ingress gateways and the Identity Platform are exposed through LoadBalancer services using the hostnames you configured during deployment. For these hostnames to resolve, you need to configure DNS in two places:

In-cluster DNS (CoreDNS), so that in-cluster workloads (for example, the authentication redirects between the gateways and the Identity Platform) can resolve the hostnames.
Host DNS, so that the machine running your browser (the cluster host itself or a separate workstation) can reach the gateways.

Get the LoadBalancer IP addresses of the gateways and the Identity Platform ingress:

UI_IP=$(kubectl -n kubeflow get svc istio-ingress-k8s-ui-istio \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
API_IP=$(kubectl -n kubeflow get svc istio-ingress-k8s-m2m-istio \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
AUTH_IP=$(kubectl -n iam-core get svc traefik-lb \
    -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo "UI   ui.kubeflow.com   -> $UI_IP"
echo "API  api.kubeflow.com  -> $API_IP"
echo "AUTH auth.kubeflow.com -> $AUTH_IP"

Configure in-cluster DNS (CoreDNS)¶

Find the CoreDNS ConfigMap name and store it in a variable to reuse it in the following steps:

COREDNS=$(kubectl -n kube-system get configmap -o name | grep coredns | head -n1 | cut -d/ -f2)
echo "$COREDNS"

The ConfigMap name depends on your K8s distribution: ck-dns-coredns on Canonical Kubernetes and coredns on MicroK8s.

Edit the CoreDNS ConfigMap:

kubectl -n kube-system edit configmap "$COREDNS"

Add a hosts block inside the .:53 { ... } server block, just before the kubernetes plugin line, using the IP addresses from step 1:

hosts {
    <UI_IP>   ui.kubeflow.com
    <API_IP>  api.kubeflow.com
    <AUTH_IP> auth.kubeflow.com
    fallthrough
}

Note

The fallthrough directive ensures that any query not matching these hostnames is still resolved by the rest of the CoreDNS configuration.

Restart CoreDNS to apply the change:

kubectl -n kube-system rollout restart deployment "$COREDNS"

Configure host DNS¶

On the machine where you access the CKF dashboard from a browser, add the hostnames to /etc/hosts using the IP addresses from step 1:

echo "$UI_IP ui.kubeflow.com"     | sudo tee -a /etc/hosts
echo "$API_IP api.kubeflow.com"   | sudo tee -a /etc/hosts
echo "$AUTH_IP auth.kubeflow.com" | sudo tee -a /etc/hosts

Create a user¶

Kubeflow profiles are owned by users whose identities are provided by the Canonical Identity Platform. Create a user in Kratos; you reference this user as the profile owner when you prepare the PMR in the next section.

Create a Kratos user using the create-admin-account action:

juju run -m iam kratos/0 create-admin-account \
   username=user1 \
   email=user1@example.com

The action output includes a link that the user opens to set their account password.

Note

Take note of the username (for example, user1). You use it as the profile owner.name in the next section.

Prepare the PMR¶

Define a Kubeflow profile in the PMR, owned by the user you created.

In the repository you created, add a pmr.yaml file at its root:

profiles:
- name: ml-engineering
  owner:
    kind: User
    name: user1

Note

You can choose any name for the profile (for example, ml-engineering); Kubeflow creates a namespace of the same name. The profile owner.name must match the Kratos username you created, so they must be identical (for example, user1). In this solution, the profile owner maps to the Identity Platform (Kratos) username, not to an email address.

See Manage profiles for the full pmr.yaml format, including contributors and resource quotas.

Commit and push the file. The github-profiles-automator charm syncs the repository and creates the profile.
Confirm that the profile has been created:

kubectl get profiles

Access CKF dashboard¶

Once DNS, the user, and the profile are ready, you can access the CKF dashboard at https://ui.kubeflow.com. You are redirected to the Canonical Identity Platform to authenticate with the user you created.

The gateways and the Identity Platform are served with certificates issued by the self-signed-certificates charm by default. Because these certificates are not signed by a trusted certificate authority (CA), your browser may warn that the connection is not trusted.

For a test or development deployment, accept the certificate warning in your browser to proceed to the login page.
For a production deployment, replace self-signed-certificates with a certificate provider backed by a trusted CA, so that browsers trust the certificates and no warning is shown.

See the Canonical Identity Platform documentation for more details on securing the Identity Platform.