Full BEL installation guide
I want to install BEL using:
I also want to enable:
My plan features:
* Recommended for production installations
Install the Gateway API
Linkerd uses Kubernetes Gateway API resources to configure certain features and must be installed first. To install the latest version of the Gateway API, run:
...If you already have the Gateway API CRDs on your cluster, you can likely just use them as is. For details, see our Managing Gateway API resources doc.
Get your license key
BEL requires a valid license key to run, which is available through the Buoyant portal. Following the instructions there, you should end up with environment variable(s) like this:
...Getting the CLI tool
Once you have your license key, the next step is to download and install the BEL CLI:
...Follow the instructions to add the linkerd CLI to your system path.
Verify that the CLI is installed and running the expected version with:
...You should see:
...Finally, validate that your cluster is ready for installation:
...Install the Linkerd CNI plugin
The Linkerd CNI plugin requires that the linkerd-cni DaemonSet be successfully installed on your cluster first, before installing the BEL control plane.
...Install BEL's lifecycle automation operator
Start by adding/updating the linkerd-buoyant repo:
...Now, we can install the BEL lifecycle automation operator itself:
...Note: Set [YOUR_CLUSTER_NAME] to the canonical name of the cluster on which you're installing the agent. This will be the name that identifies the cluster in Buoyant Cloud.
Create the TLS infrastructure
Most of Linkerd's TLS infrastructure is fully automated, but there are some things we need to generate: a trust anchor certificate and key pair, and an issuer certificate and key pair. Pay attention to the lifetimes of the certificates you are creating, especially the trust anchor, and be sure to keep these files in a safe place.
Generate trust anchor certificate
First generate the root certificate with its private key. You can generate these certificates using a tool like step.
...This generates the ca.crt and ca.key files. The ca.crt file is what you need to pass to the --identity-trust-anchors-file option when installing Linkerd with the CLI, and the identityTrustAnchorsPEM value when installing the linkerd-control-plane chart with Helm.
Note we use --no-password --insecure to avoid encrypting those files with a passphrase.
For a longer-lived trust anchor certificate, pass the --not-after argument to the step command with the desired value (e.g. --not-after=87600h).
Issuer certificate and key
Then generate the intermediate certificate and key pair that will be used to sign the Linkerd proxies’ CSR.
...This will generate the issuer.crt and issuer.key files.
Once these files are created, run the following commands:
...Configure the lifecycle operator
Next, we need to configure the BEL lifecycle automation components to be able to install Linkerd using those TLS credentials we just created.
To do this, create a CRD config that will be used by the Linkerd BEL operator to install and manage the Linkerd control plane. You will need the ca.crt file from above.
...If you are on GKE 1.29+, you need to set a custom clusterNetworks value. Learn more
...For more information see the GKE docs
Install BEL
Finally, we're ready to install BEL on your cluster! Apply the config we created in the previous step to activate the BEL lifecycle operator and install the Linkerd control plane:
...Install the Linkerd CNI plugin
The Linkerd CNI plugin requires that the linkerd-cni DaemonSet be successfully installed on your cluster first, before installing the BEL control plane.
...Create the TLS infrastructure
Most of Linkerd's TLS infrastructure is fully automated, but there are some things we need to generate: a trust anchor certificate and key pair, and an issuer certificate and key pair. Pay attention to the lifetimes of the certificates you are creating, especially the trust anchor, and be sure to keep these files in a safe place.
Generate trust anchor certificate
First generate the root certificate with its private key. You can generate these certificates using a tool like step.
...This generates the ca.crt and ca.key files. The ca.crt file is what you need to pass to the --identity-trust-anchors-file option when installing Linkerd with the CLI, and the identityTrustAnchorsPEM value when installing the linkerd-control-plane chart with Helm.
Note we use --no-password --insecure to avoid encrypting those files with a passphrase.
For a longer-lived trust anchor certificate, pass the --not-after argument to the step command with the desired value (e.g. --not-after=87600h).
Issuer certificate and key
Then generate the intermediate certificate and key pair that will be used to sign the Linkerd proxies’ CSR.
...This will generate the issuer.crt and issuer.key files.
Install BEL using Helm
Start by adding/updating the linkerd-buoyant repo:
...Now, we can install the BEL components using the ca.crt, issuer.crt, and issuer.key files from above:
...If you are on GKE 1.29+, you need to set a custom clusterNetworks value. Learn more
...For more information see the GKE docs
Install the Linkerd CNI plugin
The Linkerd CNI plugin requires that the linkerd-cni DaemonSet be successfully installed on your cluster first, before installing the BEL control plane.
...Install BEL using the CLI
Using the CLI to install BEL is quick and easy, but note that the TLS certificates generated by this installation will expire in a year. If you expect your Linkerd installation to run for more than a year, please use Helm or BEL's lifecycle operator.
To install BEL, run:
...If you are on GKE 1.29+, you need to set a custom clusterNetworks value. Learn more
...For more information see the GKE docs
Verify your installation
After the installation is complete, you can verify the health and configuration of Linkerd by running the linkerd check command:
...That's it!
You have successfully installed the enterprise distribution of Linkerd onto your Kubernetes cluster, in such a way that (thanks to the lifecycle automation operator) future upgrades are trivial and can be managed in a purely declarative, GitOps workflow.
You have successfully installed the enterprise distribution of Linkerd onto your Kubernetes cluster.
You have successfully installed the enterprise distribution of Linkerd onto your Kubernetes cluster. Note that your installation is optimized for non-production traffic such as demos and experiments.