Skip to content

Istio Integration

OpenUnison works with Istio out-of-the-box. It's been tested with Istio's side cars and can be deployed to use Istio as an Ingress controller. When deploying with Istio, your helm chart will create the appropriate Gateway, VirtualService, and Destination objects depending on your configuration choices. The Service objects will be named appropriately for Kiali to visualize the connections.

Deployment

First, add a label to the openunison namespace so Istio knows to add the envoy side cars:

kubectl label namespace openunison istio-injection=enabled

In your values.yaml, set:

  1. network.ingress_type: istio - Tells the helm chart to create the correct objects
  2. network.ingress_certificate: ou-tls-certificate - The value should be the name of the Secret in the namespace where Istio is running (ie istio-system) that stores the certificate Istio should use to serve access to OpenUnison
  3. network.istio.selectors - List of labels that should be used to associate the Gateway with an istio controller. Default is istio: ingressgateway
  4. network.force_redirect_to_tls: false - Stops OpenUnison from redirecting http to https, instead making the envoy sidecar proxy the TLS termination point

Once deployed, make sure you have created an ou-tls-certificate Secret in the Istio Namespace, istio-system by default. If you let OpenUnison generate its own certificate, you can run:

kubectl get secret ou-tls-certificate -n openunison -o yaml | sed 's/namespace[:] openunison/namespace: istio-system/g' | kubectl create -f -

If you are using an externally signed certificate (such as a wild card), make sure to add it as a Secret to both your openunison and istio-service namespaces with the name ou-tls-certificate. Follow the instructions for adding your external CA to your values.yaml.

With an ingress certificate deployed, you can access OpenUnison via the URL you specified in network.openunison_host and access your portal!

Kiali Integration

Add SSO for your Kiali deployment by following the instructions for Kiali in the Applications section of these docs.

No Load Balancer?

If you're running in a development environment or just don't have an external load balancer, you can configure Istio's ingress-gateway Pod to listen directly on 80 and 443 using this command:

kubectl patch deployments istio-ingressgateway -n istio-system -p '{"spec":{"template":{"spec":{"containers":[{"name":"istio-proxy","ports":[{"containerPort":15021,"protocol":"TCP"},{"containerPort":8080,"hostPort":80,"protocol":"TCP"},{"containerPort":8443,"hostPort":443,"protocol":"TCP"},{"containerPort":31400,"protocol":"TCP"},{"containerPort":15443,"protocol":"TCP"},{"containerPort":15090,"name":"http-envoy-prom","protocol":"TCP"}]}]}}}}'

Known Issues & Troubleshooting

Impersonation and kubectl exec

If using OpenUnison in impersonation mode, such as with a cloud hosted cluster, Istio can't be the TLS termination point because Envoy doesn't support the SPDY protocol used by kubectl exec, port-forward, and cp. The helm chart will automatically setup passthrough TLS to support these functions. This means that you won't get most of the telemetry on these functions to the oidc-proxy that deploys with OpenUnison. The kubectl commands generated by the portal will automatically embed the correct certificate.

If you're using impersonation with a wild card certificate or an externally signed certificate that isn't well known (ie Let's Encrypt), you'll need to create an Opaque Secret with your certificate's CA in the openunison namespace. For instance:

---
apiVersion: v1
data:
  tls.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSURFVENDQWZtZ0F3SUJBZ0lVYmtiS2ZRN29ldXJuVHpyeWdIL0dDS0kzNkUwd0RRWUpLb1pJaHZjTkFRRUwKQlFBd0dERVdNQlFHQTFVRUF3d05aVzUwWlhKd2NtbHpaUzFqWVRBZUZ3MHlNakV4TURjeE5EUTFNakphRncwegpNakV4TURReE5EUTFNakphTUJneEZqQVVCZ05WQkFNTURXVnVkR1Z5Y0hKcGMyVXRZMkV3Z2dFaU1BMEdDU3FHClNJYjNEUUVCQVFVQUE0SUJEd0F3Z2dFS0FvSUJBUUNucVZ3eVFvMjJyRzZuVVpjU2UvR21WZnI5MEt6Z3V4MDkKNDY4cFNTUWRwRHE5UlRRVU92ZkFUUEJXODF3QlJmUDEvcnlFaHNocnVBS2E5LzVoKzVCL3g4bmN4VFhwbThCNwp2RDdldHY4V3VyeUtQc0lMdWlkT0QwR1FTRVRvNzdBWE03RmZpUk9yMDFqN3c2UVB3dVB2QkpTcDNpa2lDL0RjCnZFNjZsdklFWE43ZFNnRGRkdnV2R1FORFdPWWxHWmhmNUZIVy81ZHJQSHVPOXp1eVVHK01NaTFpUCtSQk1QUmcKSWU2djhCcE9ncnNnZHRtWExhNFZNc1BNKzBYZkQwSDhjU2YvMkg2V1M0LzdEOEF1bG5QSW9LY1krRkxKUEFtMwpJVFI3L2w2UTBJUXVNU3c2QkxLYWZCRm5CVmNUUVNIN3lKZEFKNWdINFZZRHIyamtVWkwzQWdNQkFBR2pVekJSCk1CMEdBMVVkRGdRV0JCU2Y5RDVGS3dISUY3eFdxRi80OG4rci9SVFEzakFmQmdOVkhTTUVHREFXZ0JTZjlENUYKS3dISUY3eFdxRi80OG4rci9SVFEzakFQQmdOVkhSTUJBZjhFQlRBREFRSC9NQTBHQ1NxR1NJYjNEUUVCQ3dVQQpBNElCQVFCN1BsMjkrclJ2eHArVHhLT3RCZGRLeEhhRTJVRUxuYmlkaFUvMTZRbW51VmlCQVhidUVSSEF2Y0phCm5hb1plY0JVQVJ0aUxYT2poOTFBNkFvNVpET2RETllOUkNnTGI2czdDVVhSKzNLenZWRmNJVFRSdGtTTkxKMTUKZzRoallyQUtEWTFIM09zd1EvU3JoTG9GQndneGJJQ1F5eFNLaXQ0OURrK2V4c3puMUJFNzE2aWlJVmdZT0daTwp5SWF5ekJZdW1Gc3M0MGprbWhsbms1ZW5hYjhJTDRUcXBDZS9xYnZtNXdOaktaVVozamJsM2QxVWVtcVlOdVlWCmNFY1o0UXltQUJZS3k0VkUzVFJZUmJJZGV0NFY2dVlIRjVZUHlFRWlZMFRVZStYVVJaVkFtaU9jcmtqblVIT3gKMWJqelJxSlpMNVR3b0ZDZzVlZUR6dVk0WlRjYwotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==
kind: Secret
metadata:
  name: wildcard-ca
  namespace: openunison
type: Opaque

Then, in your values.yaml set impersonation.ca_secret_name to the name of the Secret you just created with your CA certificate in it. This will let the kube-oidc-proxy trust OpenUnison's identity provider.

Return to deployment

Connection Refused or Reset

If your browser tells you that the connection is refused, it's one of:

  1. Your load balancer isn't setup properly
  2. If no load balancer, you haven't setup the host ports correctly
  3. If the host ports are all configured properly and the load balancer is setup, did you create the ou-tls-certificate Secret in the istio-system Namespace?