Install UXP

Upbound Universal Crossplane (UXP) is the Upbound official enterprise-grade distribution of Crossplane for self-hosted control planes.

Install UXP into an existing Kubernetes cluster to access Upbound features like official providers or community Crossplane features.

Install Upbound Universal Crossplane

Installing UXP requires the Up command-line.

Use the up uxp install command to install UXP into the current Kubernetes cluster based on ~/.kube/config.

1
up uxp install

Up installs the latest stable UXP release into the upbound-system namespace.

Install a specific Upbound Universal Crossplane version

Install a specific version of UXP with up uxp install <version>.

The list of available versions is in the charts.upbound.io/stable listing.

Don’t include the universal-crossplane- name when using up uxp install <version>. For example, up uxp install 1.8.1-up.1

Install Upbound Universal Crossplane in a custom namespace

Install UXP into a specific namespace using the -n <NAMESPACE> option.

For example, to install UXP into the upbound-test namespace use the command

1
up uxp install -n upbound-test

Install unreleased Upbound Universal Crossplane versions

Install unreleased versions of UXP for testing or troubleshooting. Don’t install unreleased versions for production use without explicit guidance from Upbound.

Find available unreleased releases in the charts.upbound.io/main listing.

Install the latest unreleased version with the --unstable flag.

up uxp install --unstable

Install a specific release with up uxp install --unstable <version>

Don’t include the universal-crossplane- name when using up uxp install --unstable <version>. For example, up uxp install --unstable 1.9.0-up.1.rc.1.6.g3b4985a

Customize install options

Change default install settings via the command-line with --set <key>=<value> or a settings file with -f <file>.

A configuration file is the recommended method to customize the UXP install.

Provide file-based configurations as a Helm values file.

For example to configure two Crossplane pod replicas with --set:

up uxp install --set replicas=2

or with a file:

1
2
cat settings.yaml
replicas: 2
1
up uxp install -f settings.yaml

View the upbound-system pods to see two Crossplane pods deployed.

1
2
3
4
5
6
7
8
kubectl get pods -n upbound-system
NAME                                         READY   STATUS    RESTARTS        AGE
crossplane-75556d97b6-gpzq7                  1/1     Running   0               4m23s
crossplane-75556d97b6-xm8bj                  1/1     Running   0               4m23s
crossplane-rbac-manager-8f5c76d46-kvmpm      1/1     Running   0               4m23s
provider-aws-a1113cd136a1-59b8587f6f-q8bpt   1/1     Running   0               4h55m
upbound-bootstrapper-5dd76c4fb-g2fv5         1/1     Running   0               4m23s
xgql-7c4b74c458-rdsfb                        1/1     Running   2 (4m21s ago)   4m23s

Configure Upbound Universal Crossplane installed from the Amazon EKS management console

If you have installed uxp directly from the Amazon EKS management console, you need to grant crossplane and any provider additional cluster level roles.

Why are those actions needed? The uxp installation has been tailored to fit AWS requirements and the crossplane-rbac-manager has been disabled for the installation.

This means that in order to install and use any provider, you will need to configure uxp by granting additional cluster scope permissions to the crossplane pod and provider pods.

These steps are necessary only for the installations without crossplane-rbac-manager.

First grant crossplane a cluster-admin role.

1
2
3
kubectl create clusterrolebinding cluster-crossplane-admin \
        --clusterrole=cluster-admin \
        --serviceaccount upbound-system:crossplane

Next, for each installed provider, add cluster-admin role binding. Here is an example for provider AWS.

1
2
3
4
5
6
7
8
# Retrieve provider sa name
provider_aws=$(kubectl get sa -n upbound-system \
              | grep provider-aws \
              | awk '{print $1}')
# Grant cluster-admin role
kubectl create clusterrolebinding cluster-provider-aws-admin \
        --clusterrole=cluster-admin \
        --serviceaccount upbound-system:"$provider_aws"

Restart crossplane and provider aws pods for the changes to take effect

1
2
3
4
5
AWS_POD=$(kubectl get pods -n upbound-system | grep provider-aws | awk '{print $1}') && \
          kubectl delete pod -n upbound-system $AWS_POD

CROSSPLANE_POD=$(kubectl get pods -n upbound-system | grep crossplane | awk '{print $1}') && \
          kubectl delete pod -n upbound-system $CROSSPLANE_POD
ParameterDescriptionDefault
affinityEnable and define the affinity for the crossplane pod.{} - Affinities aren’t configured.
configuration.packagesThe list of configuration packages to install together with UXP. These packages install UXP resources after the crossplane pod starts.{} - Configurations aren’t installed by default.
customAnnotationsCustom annotations to add to the crossplane deployment and pod.{} - Annotations aren’t configured.
customLabelsCustom labels to add to the crossplane and crossplane-rbac-manager deployments and pods. Overwriting default labels isn’t supported and causes the install to fail.{app=crossplane, app.kubernetes.io/component=cloud-infrastructure-controller, app.kubernetes.io/instance=universal-crossplane, app.kubernetes.io/managed-by=Helm, app.kubernetes.io/name=crossplane, app.kubernetes.io/part-of=crossplane, app.kubernetes.io/version=<crossplane version>, helm.sh/chart=<crossplane version>, release=universal-crossplane}
deploymentStrategyThe deployment strategy for the crossplane and crossplane-rbac-manager pods.RollingUpdate
extraEnvVarsCrossplaneList of extra environment variables to set in the crossplane deployment. A _ replaces any . character in a variable name. For example SAMPLE.KEY=value1 becomes SAMPLE\_KEY=value1.{POD_NAMESPACE:(v1:metadata.namespace),olala:olala,LEADER_ELECTION:true}
extraEnvVarsRBACManagerList of extra environment variables to set in the crossplane-rbac-manager deployment. A _ replaces any . character in a variable name. For example SAMPLE.KEY=value1 becomes SAMPLE\_KEY=value1.{LEADER_ELECTION:true}
image.pullPolicyKubernetes image pull policy.IfNotPresent
image.repositoryContainer image repository to download UXP from.The DockerHub repository upbound/crossplane.
image.tagImage tag to install a specific Crossplane version. Provides the same function as up uxp install <image.tag>."" - Without an image tag Up installs the latest UXP version.
imagePullSecretsList of Kubernetes image pull secrets. Required if image.repository uses authentication."" - Secrets aren’t configured.
leaderElectionEnable leader election for the crossplane deployment and pods. Set leaderElection as true for any deployment with more than 1 replica to prevent race-conditions.true
metrics.enabledExposes port 8080 in the crossplane and crossplane-rbac-manager pods. Configures pod annotations prometheus.io/path:/metrics, prometheus.io/port:"8080" and prometheus.io/scrape:"true".false
nodeSelectorApply a nodeSelector map to the crossplane pod.{} - Node selectors aren’t configured.
packageCache.mediumThe Kubernetes emptyDir Volume type for the crossplane pod’s package cache. The only valid value is "memory". Not supported with packageCache.pvc."" - Kubernetes pod default of local node storage.
packageCache.pvcA PersistentVolumeClaim for the crossplane pod’s package cache. packageCache.pvc is an alternative to the default emptyDir volume mount. Not supported with packageCache.medium or packageCache.sizeLimit."" - emptyDir is the default mounted pod volume.
packageCache.sizeLimitThe size limit for the crossplane pod’s emptyDir package cache. Not supported with pacakgeCache.pvc.5Mi
priorityClassNameApplies a priority class name to the crossplane and crossplane-rbac-manager deployments and pods."" - A priority class isn’t set.
provider.packagesThe list of provider packages to install together with UXP. These packages install UXP resources after the crossplane pod starts.[] - Providers aren’t installed by default.
rbacManager.affinityEnable and define the affinity for the crossplane pod.{} - Affinities aren’t configured.
rbacManager.deployDeploy RBAC Manager and its required roles.true
rbacManager.leaderElectionEnable leader election for the crossplane-rbac-manager deployment and pods. Set leaderElection as true for any deployment with more than 1 replica to prevent race-conditions.true
rbacManager.managementPolicyThe scope of crossplane-rbac-manager permissions control. A value of all all Crossplane controller and user roles. basic only manages Crossplane controller roles and the crossplane-admin, crossplane-edit, and crossplane-view user roles.all
rbacManager.nodeSelectorApply a nodeSelector map to the crossplane pod.{} - Node selectors aren’t configured.
rbacManager.replicasThe number of crossplane-rbac-manager replicas.1
rbacManager.skipAggregatedClusterRolesSkip the deployment of ClusterRoles along with the crossplane-rbac-manager. Set to true to manually build Crossplane ClusterRoles.false
rbacManager.tolerationsEnable tolerations for the crossplane-rbac-manager pod.{} - Tolerations aren’t configured.
registryCaBundleConfig.keyUse a custom CA certification for downloading images and configurations. The value of the configMap key. Use with registryCaBundleConfig.name{} - Crossplane uses the default system certificates.
registryCaBundleConfig.nameUse a custom CA certification for downloading images and configurations. The value of the configMap name. Use with registryCaBundleConfig.key{} - Crossplane uses the default system certificates.
replicasThe number of crossplane-rbac-manager replicas.1
resourcesCrossplane.limits.cpuCPU resource limits for the crossplane pods.100m
resourcesCrossplane.limits.memoryMemory resource limits for the crossplane pods.512Mi
resourcesCrossplane.requests.cpuCPU resource requests for the crossplane pods.100m
resourcesCrossplane.requests.memoryMemory resource requests for the crossplane pods.256Mi
resourcesRBACManager.limits.cpuCPU resource limits for the crossplane-rbac-manager pods.100m
resourcesRBACManager.limits.memoryMemory resource limits for the crossplane-rbac-manager pods.512Mi
resourcesRBACManager.requests.cpuCPU resource requests for the crossplane-rbac-manager pods.100m
resourcesRBACManager.requests.memoryMemory resource requests for the crossplane-rbac-manager pods.256Mi
securityContextCrossplane.allowPrivilegeEscalationAllow privilege escalation the crossplane pods.false
securityContextCrossplane.readOnlyRootFilesystemSet a ReadOnly root file system for the crossplane pods.true
securityContextCrossplane.runAsGroupSet the Run as group for the crossplane pods.65532
securityContextCrossplane.runAsUserSet the Run as user the crossplane pods.65532
securityContextRBACManager.allowPrivilegeEscalationAllow privilege escalation the crossplane-rbac-manager pods.false
securityContextRBACManager.readOnlyRootFilesystemSet a ReadOnly root file system for the crossplane-rbac-manager pods.true
securityContextRBACManager.runAsGroupSet the Run as group for the crossplane-rbac-manager pods.65532
securityContextRBACManager.runAsUserSet the Run as user the crossplane-rbac-manager pods.65532
serviceAccount.customAnnotationsCustom annotations for the crossplane serviceaccount{meta.helm.sh/release-name: universal-crossplane, meta.helm.sh/release-namespace: upbound-system}
tolerationsEnable tolerations for the crossplane pod.{} - Tolerations aren’t configured.
webhooks.enabledCreate a service and expose TCP port 9443 to support webhooks for all Crossplane created pods.false