Multi-user, auth-enabled Kubeflow with kfctl_istio_dex

Instructions for installing Kubeflow with kfctl_istio_dex.yaml config

Follow these instructions if you want to install Kubeflow on an existing Kubernetes cluster.

This installation of Kubeflow is geared towards existing Kubernetes clusters and does not depend on any cloud-specific feature.

Architecture overview

In this reference architecture, we use Dex and Istio for vendor-neutral authentication.

This deployment works well for on-premises installations, where companies/organizations need LDAP/AD integration for multi-user authentication, and they don’t want to depend on any cloud-specific feature.

kfctl_istio_dex_architecture

Read the relevant article for more info about this architecture.

Before you start

The instructions below assume that you have an existing Kubernetes cluster.

Default StorageClass for on-premises deployments

This Kubeflow deployment requires a default StorageClass with a dynamic volume provisioner. Verify the provisioner field of your default StorageClass definition. If you don’t have a provisioner, ensure that you have configured volume provisioning in your Kubernetes cluster appropriately as mentioned below.

Notes on the configuration file

Configuring your installation with kfctl_istio_dex.v1.2.0.yaml has a few options you should consider:

  • Disabling istio installation - If your Kubernetes cluster has an existing Istio installation you may choose to not install Istio by removing the applications istio-crds and istio-install in the configuration file kfctl_istio_dex.v1.2.0.yaml.

  • Istio configuration for trustworthy JWTs - This configuration uses Istio version 1.3.1 with SDS enabled, which requires Kubernetes 1.13 or later. Follow Istio’s blog to add API server configurations to your Kubernetes cluster. Ensure that the TokenRequest feature flag is set to true in the cluster. For kubeadm created clusters, set the API server flags in the pod manifest at /etc/kubernetes/manifests/kube-apiserver.yaml. For example, the Istio community runs their test-infrastructure with the following API server flags:

    1. "service-account-issuer": "kubernetes.default.svc"
    2. "service-account-signing-key-file": "/etc/kubernetes/pki/sa.key"

  • Default password in static file configuration for Dex - The configuration file kfctl_istio_dex.v1.2.0.yaml contains a default staticPasswords user with email set to admin@kubeflow.org and password 12341234. You should change this configuration or replace it with a Dex connector.

Prepare your environment

Follow these steps to download the kfctl binary for the Kubeflow CLI and set some handy environment variables:

  1. Download the kfctl v1.2.0 release from the Kubeflow releases page.

  2. Unpack the tar ball:

    1. tar -xvf kfctl_<release tag>_<platform>.tar.gz

  3. Create environment variables to make the deployment process easier:

  1. # Add kfctl to PATH, to make the kfctl binary easier to use.
  2. # Use only alphanumeric characters or - in the directory name.
  3. export PATH=$PATH:"<path-to-kfctl>"
  5. # Set the following kfctl configuration file:
  6. export CONFIG_URI="https://raw.githubusercontent.com/kubeflow/manifests/v1.2-branch/kfdef/kfctl_istio_dex.v1.2.0.yaml"
  8. # Set KF_NAME to the name of your Kubeflow deployment. You also use this
  9. # value as directory name when creating your configuration directory.
  10. # For example, your deployment name can be 'my-kubeflow' or 'kf-test'.
  11. export KF_NAME=<your choice of name for the Kubeflow deployment>
  13. # Set the path to the base directory where you want to store one or more 
  14. # Kubeflow deployments. For example, /opt.
  15. # Then set the Kubeflow application directory for this deployment.
  16. export BASE_DIR=<path to a base directory>
  17. export KF_DIR=${BASE_DIR}/${KF_NAME}

Notes:

  • ${KF_NAME} - The name of your Kubeflow deployment. If you want a custom deployment name, specify that name here. For example, my-kubeflow or kf-test. The value of KF_NAME must consist of lower case alphanumeric characters or ‘-‘, and must start and end with an alphanumeric character. The value of this variable cannot be greater than 25 characters. It must contain just a name, not a directory path. You also use this value as directory name when creating the directory where your Kubeflow configurations are stored, that is, the Kubeflow application directory.

  • ${KF_DIR} - The full path to your Kubeflow application directory.

  • ${CONFIG_URI} - The GitHub address of the configuration YAML file that you want to use to deploy Kubeflow. The URI used in this guide is https://raw.githubusercontent.com/kubeflow/manifests/v1.2-branch/kfdef/kfctl_istio_dex.v1.2.0.yaml. When you run kfctl apply or kfctl build (see the next step), kfctl creates a local version of the configuration YAML file which you can further customize if necessary.

Set up and deploy Kubeflow

To set up and deploy Kubeflow using the default settings, run the kfctl apply command:

  1. mkdir -p ${KF_DIR}
  2. cd ${KF_DIR}
  4. # Download the config file and change the default login credentials.
  5. wget -O kfctl_istio_dex.yaml $CONFIG_URI
  6. export CONFIG_FILE=${KF_DIR}/kfctl_istio_dex.yaml
  8. # Credentials for the default user are admin@kubeflow.org:12341234
  9. # To change them, please edit the dex-auth application parameters
  10. # inside the KfDef file.
  11. vim $CONFIG_FILE
  13. kfctl apply -V -f ${CONFIG_FILE}

Alternatively, set up your configuration for later deployment

If you want to customize your configuration before deploying Kubeflow, you can set up your configuration files first, then edit the configuration, then deploy Kubeflow:

  1. Run the kfctl build command to set up your configuration:

    1. mkdir -p ${KF_DIR}
    2. cd ${KF_DIR}
    3. kfctl build -V -f ${CONFIG_URI}

  2. Edit the configuration files, as described in the guide to customizing your Kubeflow deployment.

  3. Set an environment variable pointing to your local configuration file:

    1. export CONFIG_FILE=${KF_DIR}/kfctl_istio_dex.yaml

  4. Run the kfctl apply command to deploy Kubeflow:

    1. kfctl apply -V -f ${CONFIG_FILE}

Accessing Kubeflow

Log in as a static user

The default way of accessing Kubeflow is via port-forward. This enables you to get started quickly without imposing any requirements on your environment.

  1. # Kubeflow will be available at localhost:8080
  2. kubectl port-forward svc/istio-ingressgateway -n istio-system 8080:80

The credentials are the ones you specified in the KfDef file, or the default (admin@kubeflow.org:12341234). It is highly recommended to change the default credentials. To add static users or change the existing one, see the relevant section.

When you’re ready, you can expose your Kubeflow deployment with a LoadBalancer Service or an Ingress. For more information, see the expose kubeflow section.

Add static users for basic auth

To add users to basic auth, you just have to edit the Dex ConfigMap under the key staticPasswords.

  1. # Download the dex config
  2. kubectl get configmap dex -n auth -o jsonpath='{.data.config\.yaml}' > dex-config.yaml
  4. # Edit the dex config with extra users.
  5. # The password must be hashed with bcrypt with an at least 10 difficulty level.
  6. # You can use an online tool like: https://passwordhashing.com/BCrypt
  8. # After editing the config, update the ConfigMap
  9. kubectl create configmap dex --from-file=config.yaml=dex-config.yaml -n auth --dry-run -oyaml | kubectl apply -f -
  11. # Restart Dex to pick up the changes in the ConfigMap
  12. kubectl rollout restart deployment dex -n auth

Log in with LDAP / Active Directory

As you saw in the overview, we use Dex for providing user authentication. Dex supports several authentication methods:

  • Static users, as described above
  • LDAP / Active Directory
  • External Identity Provider (IdP) (for example Google, LinkedIn, GitHub, …)

This section focuses on setting up Dex to authenticate with an existing LDAP database.

  1. (Optional) If you don’t have an LDAP database, you can set one up following these instructions:

    1. Deploy a new LDAP Server as a StatefulSet. This also deploys phpLDAPadmin, a GUI for interacting with your LDAP Server.

      LDAP Server Manifest

      1.         apiVersion: v1
      2.         kind: Service
      3.         metadata:
      4.           labels:
      5.             app: ldap
      6.           name: ldap-service
      7.           namespace: kubeflow
      8.         spec:
      9.           type: ClusterIP
      10.           clusterIP: None
      11.           ports:
      12.             - port: 389
      13.           selector:
      14.             app: ldap
      15.         ---
      17.         apiVersion: apps/v1
      18.         kind: StatefulSet
      19.         metadata:
      20.           name: ldap
      21.           namespace: kubeflow
      22.           labels:
      23.             app: ldap
      24.         spec:
      25.           serviceName: ldap-service
      26.           replicas: 1
      27.           selector:
      28.             matchLabels:
      29.               app: ldap
      30.           template:
      31.             metadata:
      32.               labels:
      33.                 app: ldap
      34.             spec:
      35.               containers:
      36.                 - name: ldap
      37.                   image: osixia/openldap:1.2.4
      38.                   volumeMounts:
      39.                     - name: ldap-data
      40.                       mountPath: /var/lib/ldap
      41.                     - name: ldap-config
      42.                       mountPath: /etc/ldap/slapd.d
      43.                   ports:
      44.                     - containerPort: 389
      45.                       name: openldap
      46.                   env:
      47.                     - name: LDAP_LOG_LEVEL
      48.                       value: "256"
      49.                     - name: LDAP_ORGANISATION
      50.                       value: "Example"
      51.                     - name: LDAP_DOMAIN
      52.                       value: "example.com"
      53.                     - name: LDAP_ADMIN_PASSWORD
      54.                       value: "admin"
      55.                     - name: LDAP_CONFIG_PASSWORD
      56.                       value: "config"
      57.                     - name: LDAP_BACKEND
      58.                       value: "mdb"
      59.                     - name: LDAP_TLS
      60.                       value: "false"
      61.                     - name: LDAP_REPLICATION
      62.                       value: "false"
      63.                     - name: KEEP_EXISTING_CONFIG
      64.                       value: "false"
      65.                     - name: LDAP_REMOVE_CONFIG_AFTER_SETUP
      66.                       value: "true"
      67.               volumes:
      68.                 - name: ldap-config
      69.                   emptyDir: {}
      70.           volumeClaimTemplates:
      71.               - metadata:
      72.                   name: ldap-data
      73.                 spec:
      74.                   accessModes: [ "ReadWriteOnce" ]
      75.                   resources:
      76.                     requests:
      77.                       storage: 10Gi
      79.         ---
      81.         apiVersion: v1
      82.         kind: Service
      83.         metadata:
      84.           labels:
      85.             app: phpldapadmin
      86.           name: phpldapadmin-service
      87.           namespace: kubeflow
      88.         spec:
      89.           type: ClusterIP
      90.           ports:
      91.             - port: 80
      92.           selector:
      93.             app: phpldapadmin
      95.         ---
      97.         apiVersion: apps/v1
      98.         kind: Deployment
      99.         metadata:
      100.           name: phpldapadmin
      101.           namespace: kubeflow
      102.           labels:
      103.             app: phpldapadmin
      104.         spec:
      105.           replicas: 1
      106.           selector:
      107.             matchLabels:
      108.               app: phpldapadmin
      109.           template:
      110.             metadata:
      111.               labels:
      112.                 app: phpldapadmin
      113.             spec:
      114.               containers:
      115.                 - name: phpldapadmin
      116.                   image: osixia/phpldapadmin:0.8.0
      117.                   ports:
      118.                     - name: http-server
      119.                       containerPort: 80
      120.                   env:
      121.                     - name: PHPLDAPADMIN_HTTPS
      122.                       value: "false"
      123.                     - name: PHPLDAPADMIN_LDAP_HOSTS
      124.                       value : "#PYTHON2BASH:[{'ldap-service.kubeflow.svc.cluster.local': [{'server': [{'tls': False}]},{'login': [        {'bind_id': 'cn=admin,dc=example,dc=com'}]}]}]"

    2. Seed the LDAP database with new entries.

      1. kubectl exec -it -n kubeflow ldap-0 -- bash
      2. ldapadd -x -D "cn=admin,dc=example,dc=com" -W
      3. # Enter password "admin".
      4. # Press Ctrl+D to complete after pasting the snippet below.

      LDAP Seed Users and Groups

      1. # If you used the OpenLDAP Server deployment in step 1,
      2. # then this object already exists.
      3. # If it doesn't, uncomment this.
      4. #dn: dc=example,dc=com
      5. #objectClass: dcObject
      6. #objectClass: organization
      7. #o: Example
      8. #dc: example
      10. dn: ou=People,dc=example,dc=com
      11. objectClass: organizationalUnit
      12. ou: People
      14. dn: cn=Nick Kiliadis,ou=People,dc=example,dc=com
      15. objectClass: person
      16. objectClass: inetOrgPerson
      17. givenName: Nick
      18. sn: Kiliadis
      19. cn: Nick Kiliadis
      20. uid: nkili
      21. mail: nkili@example.com
      22. userpassword: 12341234
      24. dn: cn=Robin Spanakopita,ou=People,dc=example,dc=com
      25. objectClass: person
      26. objectClass: inetOrgPerson
      27. givenName: Robin
      28. sn: Spanakopita
      29. cn: Robin Spanakopita
      30. uid: rspanakopita
      31. mail: rspanakopita@example.com
      32. userpassword: 43214321
      34. # Group definitions.
      36. dn: ou=Groups,dc=example,dc=com
      37. objectClass: organizationalUnit
      38. ou: Groups
      40. dn: cn=admins,ou=Groups,dc=example,dc=com
      41. objectClass: groupOfNames
      42. cn: admins
      43. member: cn=Nick Kiliadis,ou=People,dc=example,dc=com
      45. dn: cn=developers,ou=Groups,dc=example,dc=com
      46. objectClass: groupOfNames
      47. cn: developers
      48. member: cn=Nick Kiliadis,ou=People,dc=example,dc=com
      49. member: cn=Robin Spanakopita,ou=People,dc=example,dc=com

  2. To use your LDAP/AD server with Dex, you have to edit the Dex config. To edit the ConfigMap containing the Dex config, follow these steps:

    1. Get the current Dex config from the corresponding Config Map.

      1.         kubectl get configmap dex -n auth -o jsonpath='{.data.config\.yaml}' > dex-config.yaml

    2. Add the LDAP-specific options. Here is an example to help you out. It is configured to work with the example LDAP Server you set up previously.

      Dex LDAP Config Section

      1.         connectors:
      2.         - type: ldap
      3.           # Required field for connector id.
      4.           id: ldap
      5.           # Required field for connector name.
      6.           name: LDAP
      7.           config:
      8.             # Host and optional port of the LDAP server in the form "host:port".
      9.             # If the port is not supplied, it will be guessed based on "insecureNoSSL",
      10.             # and "startTLS" flags. 389 for insecure or StartTLS connections, 636
      11.             # otherwise.
      12.             host: ldap-service.kubeflow.svc.cluster.local:389
      14.             # Following field is required if the LDAP host is not using TLS (port 389).
      15.             # Because this option inherently leaks passwords to anyone on the same network
      16.             # as dex, THIS OPTION MAY BE REMOVED WITHOUT WARNING IN A FUTURE RELEASE.
      17.             #
      18.             insecureNoSSL: true
      20.             # If a custom certificate isn't provide, this option can be used to turn off
      21.             # TLS certificate checks. As noted, it is insecure and shouldn't be used outside
      22.             # of explorative phases.
      23.             #
      24.             insecureSkipVerify: true
      26.             # When connecting to the server, connect using the ldap:// protocol then issue
      27.             # a StartTLS command. If unspecified, connections will use the ldaps:// protocol
      28.             #
      29.             startTLS: false
      31.             # Path to a trusted root certificate file. Default: use the host's root CA.
      32.             # rootCA: /etc/dex/ldap.ca
      33.             # clientCert: /etc/dex/ldap.cert
      34.             # clientKey: /etc/dex/ldap.key
      36.             # A raw certificate file can also be provided inline.
      37.             # rootCAData: ( base64 encoded PEM file )
      39.             # The DN and password for an application service account. The connector uses
      40.             # these credentials to search for users and groups. Not required if the LDAP
      41.             # server provides access for anonymous auth.
      42.             # Please note that if the bind password contains a `$`, it has to be saved in an
      43.             # environment variable which should be given as the value to `bindPW`.
      44.             bindDN: cn=admin,dc=example,dc=com
      45.             bindPW: admin
      47.             # The attribute to display in the provided password prompt. If unset, will
      48.             # display "Username"
      49.             usernamePrompt: username
      51.             # User search maps a username and password entered by a user to a LDAP entry.
      52.             userSearch:
      53.               # BaseDN to start the search from. It will translate to the query
      54.               # "(&(objectClass=person)(uid=<username>))".
      55.               baseDN: ou=People,dc=example,dc=com
      56.               # Optional filter to apply when searching the directory.
      57.               filter: "(objectClass=inetOrgPerson)"
      59.               # username attribute used for comparing user entries. This will be translated
      60.               # and combined with the other filter as "(<attr>=<username>)".
      61.               username: uid
      62.               # The following three fields are direct mappings of attributes on the user entry.
      63.               # String representation of the user.
      64.               idAttr: uid
      65.               # Required. Attribute to map to Email.
      66.               emailAttr: mail
      67.               # Maps to display name of users. No default value.
      68.               nameAttr: givenName
      70.             # Group search queries for groups given a user entry.
      71.             groupSearch:
      72.               # BaseDN to start the search from. It will translate to the query
      73.               # "(&(objectClass=group)(member=<user uid>))".
      74.               baseDN: ou=Groups,dc=example,dc=com
      75.               # Optional filter to apply when searching the directory.
      76.               filter: "(objectClass=groupOfNames)"
      78.               # Following two fields are used to match a user to a group. It adds an additional
      79.               # requirement to the filter that an attribute in the group must match the user's
      80.               # attribute value.
      81.               userAttr: DN
      82.               groupAttr: member
      84.               # Represents group name.
      85.               nameAttr: cn

    3. Append the LDAP config section to the dex config.

      1.         cat dex-config.yaml dex-config-ldap-partial.yaml > dex-config-final.yaml

    4. Apply the new config.

      1.         kubectl create configmap dex --from-file=config.yaml=dex-config-final.yaml -n auth --dry-run -oyaml | kubectl apply -f -

    5. Restart the Dex deployment: kubectl rollout restart deployment dex -n auth

Expose Kubeflow

While port-forward is a great way to get started, it is not a long-term, production-ready solution. In this section, we explore the process of exposing your cluster to the outside world.

NOTE: It is highly recommended to change the default credentials before exposing your Kubeflow cluster. See the relevant section for how to edit Dex static users.

Secure with HTTPS

Since we are exposing our cluster to the outside world, it’s important to secure it with HTTPS. Here we will configure automatic self-signed certificates.

Edit the Istio Gateway Object and expose port 443 with HTTPS. In addition, make port 80 redirect to 443:

  1. kubectl edit -n kubeflow gateways.networking.istio.io kubeflow-gateway

The Gateway Spec should look like the following:

  1. spec:
  2.   selector:
  3.     istio: ingressgateway
  4.   servers:
  5.   - hosts:
  6.     - '*'
  7.     port:
  8.       name: http
  9.       number: 80
  10.       protocol: HTTP
  11.     # Upgrade HTTP to HTTPS
  12.     tls:
  13.       httpsRedirect: true
  14.   - hosts:
  15.     - '*'
  16.     port:
  17.       name: https
  18.       number: 443
  19.       protocol: HTTPS
  20.     tls:
  21.       mode: SIMPLE
  22.       privateKey: /etc/istio/ingressgateway-certs/tls.key
  23.       serverCertificate: /etc/istio/ingressgateway-certs/tls.crt

Expose with a LoadBalancer

If you don’t have support for LoadBalancer on your cluster, please follow the instructions below to deploy MetalLB in Layer 2 mode. (You can read more about Layer 2 mode in the MetalLB docs.)

MetalLB deployment

Deploy MetalLB:

  1. Apply the manifest:

    1. kubectl apply -f https://raw.githubusercontent.com/google/metallb/v0.8.1/manifests/metallb.yaml

  2. Allocate a pool of addresses on your local network for MetalLB to use. You need at least one address for the Istio Gateway. This example assumes addresses 10.0.0.100-10.0.0.110. You must modify these addresses based on your environment.

    1. cat <<EOF | kubectl apply -f -
    2. apiVersion: v1
    3. kind: ConfigMap
    4. metadata:
    5.   namespace: metallb-system
    6.   name: config
    7. data:
    8.   config: |
    9.     address-pools:
    10.     - name: default
    11.       protocol: layer2
    12.       addresses:
    13.       - 10.0.0.100-10.0.0.110
    14. EOF

Ensure that MetalLB works as expected (optional):

  1. Create a dummy service:

    1. kubectl create service loadbalancer nginx --tcp=80:80
    2. service/nginx created

  2. Ensure that MetalLB has allocated an IP address for the service:

    1. kubectl describe service nginx
    2. ...
    3. Events:
    4.   Type    Reason       Age   From                Message
    5.   ----    ------       ----  ----                -------
    6.   Normal  IPAllocated  69s   metallb-controller  Assigned IP "10.0.0.101"

  3. Check the corresponding MetalLB logs:

    1. kubectl logs -n metallb-system -l component=controller
    2. ...
    3. {"caller":"service.go:98","event":"ipAllocated","ip":"10.0.0.101","msg":"IP address assigned by controller","service":"default/nginx","ts":"2019-08-09T15:12:09.376779263Z"}

  4. Create a pod that will be exposed with the service:

    1. kubectl run nginx --image nginx --restart=Never -l app=nginx
    2. pod/nginx created

  5. Ensure that MetalLB has assigned a node to announce the allocated IP address:

    1. kubectl describe service nginx
    2. ...
    3. Events:
    4.   Type    Reason       Age   From                Message
    5.   ----    ------       ----  ----                -------
    6.    Normal  nodeAssigned  4s    metallb-speaker     announcing from node "node-2"

  6. Check the corresponding MetalLB logs:

    1. kubectl logs -n metallb-system -l component=speaker
    2. ...
    3. {"caller":"main.go:246","event":"serviceAnnounced","ip":"10.0.0.101","msg":"service has IP, announcing","pool":"default","protocol":"layer2","service":"default/nginx","ts":"2019-08-09T15:14:02.433876894Z"}

  7. Check that MetalLB responds to ARP requests for the allocated IP address:

    1. arping -I eth0 10.0.0.101
    2. ...
    3. ARPING 10.0.0.101 from 10.0.0.204 eth0
    4. Unicast reply from 10.0.0.101 [6A:13:5A:D2:65:CB]  2.619ms

  8. Check the corresponding MetalLB logs:

    1. kubectl logs -n metallb-system -l component=speaker
    2. ...
    3. {"caller":"arp.go:102","interface":"eth0,"ip":"10.0.0.101","msg":"got ARP request for service IP, sending response","responseMAC":"6a:13:5a:d2:65:cb","senderIP":"10.0.0.204","senderMAC":"9a:1f:7c:95:ca:dc","ts":"2019-08-09T15:14:52.912056021Z"}

  9. Verify that everything works as expected:

    1. curl http://10.0.0.101
    2. ...
    3. <p><em>Thank you for using nginx.</em></p>
    4. ...

  10. Clean up:

    1. kubectl delete service nginx
    2. kubectl delete pod nginx

To expose Kubeflow with a LoadBalancer Service, just change the type of the istio-ingressgateway Service to LoadBalancer.

  1. kubectl patch service -n istio-system istio-ingressgateway -p '{"spec": {"type": "LoadBalancer"}}'

After that, get the LoadBalancer’s IP or Hostname from its status and create the necessary certificate.

  1. kubectl get svc -n istio-system istio-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0]}'

Create the Certificate with cert-manager:

  1. apiVersion: cert-manager.io/v1alpha2
  2. kind: Certificate
  3. metadata:
  4.   name: istio-ingressgateway-certs
  5.   namespace: istio-system
  6. spec:
  7.   commonName: istio-ingressgateway.istio-system.svc
  8.   # Use ipAddresses if your LoadBalancer issues an IP
  9.   ipAddresses:
  10.   - <LoadBalancer IP>
  11.   # Use dnsNames if your LoadBalancer issues a hostname (eg on AWS)
  12.   dnsNames:
  13.   - <LoadBalancer HostName>
  14.   isCA: true
  15.   issuerRef:
  16.     kind: ClusterIssuer
  17.     name: kubeflow-self-signing-issuer
  18.   secretName: istio-ingressgateway-certs

After applying the above Certificate, cert-manager will generate the TLS certificate inside the istio-ingressgateway-certs secrets. The istio-ingressgateway-certs secret is mounted on the istio-ingressgateway deployment and used to serve HTTPS.

Navigate to https://<LoadBalancer Address>/ and start using Kubeflow.

Delete Kubeflow

Run the following commands to delete your deployment and reclaim all resources:

  1. cd ${KF_DIR}
  2. # If you want to delete all the resources, run:
  3. kfctl delete -f ${CONFIG_FILE}

Understanding the deployment process

The kfctl deployment process includes the following commands:

  • kfctl build - (Optional) Creates configuration files defining the various resources in your deployment. You only need to run kfctl build if you want to edit the resources before running kfctl apply.
  • kfctl apply - Creates or updates the resources.
  • kfctl delete - Deletes the resources.

Application layout

Your Kubeflow application directory ${KF_DIR} contains the following files and directories:

  • ${CONFIG_FILE} is a YAML file that defines configurations related to your Kubeflow deployment.

  • kustomize is a directory that contains the kustomize packages for Kubeflow applications. See how Kubeflow uses kustomize.

    • The directory is created when you run kfctl build or kfctl apply.
    • You can customize the Kubernetes resources by modifying the manifests and running kfctl apply again.

We recommend that you check in the contents of your ${KF_DIR} directory into source control.

Provisioning of Persistent Volumes in Kubernetes

Note that you can skip this step if you have a dynamic volume provisioner already installed in your cluster.

If you don’t have one:

  • You can choose to create PVs manually after deployment of Kubeflow.
  • Or install a dynamic volume provisioner like Local Path Provisioner. Ensure that the StorageClass used by this provisioner is the default StorageClass.

Troubleshooting

Persistent Volume Claims are in Pending State

Check if PersistentVolumeClaims get Bound to PersistentVolumes.

  1. kubectl -n kubeflow get pvc

If the PersistentVolumeClaims (PVCs) are in Pending state after deployment and they are not bound to PersistentVolumes (PVs), you may have to either manually create PVs for each PVC in your Kubernetes Cluster or an alternative is to set up dynamic volume provisioning to create PVs on demand and redeploy Kubeflow after deleting existing PVCs.

Kubeflow dashboard is not available

If the Kubeflow dashboard is not available at https://<kubeflow address> ensure that:

  1. the virtual services have been created:

    1. kubectl get virtualservices -n kubeflow
    2. kubectl get virtualservices -n kubeflow centraldashboard -o yaml

    If not, then kfctl has aborted for some reason, and not completed successfully.

  2. OIDC auth service redirects you to Dex:

    1. curl -k https://<kubeflow address>/ -v
    2. ...
    3. < HTTP/2 302
    4. < content-type: text/html; charset=utf-8
    5. < location:
    6. /dex/auth?client_id=kubeflow-authservice-oidc&redirect_uri=%2Flogin%2Foidc&response_type=code&scope=openid+profile+email+groups&state=vSCMnJ2D
    7. < date: Fri, 09 Aug 2019 14:33:21 GMT
    8. < content-length: 181
    9. < x-envoy-upstream-service-time: 0
    10. < server: istio-envoy

Some additional debugging information:

OIDC AuthService logs:

  1. kubectl logs -n istio-system -l app=authservice

Dex logs:

  1. kubectl logs -n auth -l app=dex

Istio ingress-gateway logs:

  1. kubectl logs -n istio-system -l istio=ingressgateway

Istio ingressgateway service:

  1. kubectl get service -n istio-system istio-ingressgateway -o yaml

MetalLB logs:

  1. kubectl logs -n metallb-system -l component=speaker
  2. ...
  3. {"caller":"arp.go:102","interface":"br100","ip":"10.0.0.100","msg":"got ARP request for service IP, sending response","responseMAC":"62:41:bd:5f:cc:0d","senderIP":"10.0.0.204","senderMAC":"9a:1f:7c:95:ca:dc","ts":"2019-07-31T13:19:19.7082836Z"}
  1. kubectl logs -n metallb-system  -l component=controller
  2. ...
  3. {"caller":"service.go:98","event":"ipAllocated","ip":"10.0.0.100","msg":"IP address assigned by controller","service":"istio-system/istio-ingressgateway","ts":"2019-07-31T12:17:46.234638607Z"}

Please join the Kubeflow Slack to report any issues, request help, and give us feedback on this config.

Next steps

Last modified 20.04.2021: Apply Docs Restructure to `v1.2-branch` = update `v1.2-branch` to current `master` v2 (#2612) (4e2602bd)