Managing Edge

Modifying Edge

You can configure Edge using the c8yedge tool, if you have installed Edge using the tool. You can also configure Edge by making changes to the custom resource (CR), an object in Kubernetes representing this Edge installation.

Configuring with the c8yedge tool

After installing Edge using the c8yedge tool, you might want to configure an SSL certificate for your Edge, give it a custom domain, and set the Edge tenant’s name (company name) and the admin user email. This can be achieved by using the config command of the c8yedge tool.

First, ensure that your certificate and private key are in separate files, in PEM format. Then use the following command to configure your domain, license key, and SSL certificate.

c8yedge config \
  --set domain=<DOMAIN-NAME> \
  --set-file licenseKey=<path/to/license.txt> \
  --set-file tlsSecret.tls.key=<path/to/tls.key> \
  --set-file tlsSecret.tls.crt=<path/to/tls.crt>

Note that the license key must always be valid for the domain name, so any change of domain name should be made simultaneously with a change of license key.

Use the following command to modify the Edge tenant’s name and the administrator’s email address.

c8yedge config \
  --set company=<COMPANY-NAME> \
  --set email=<ADMIN-EMAIL>

Note that the company name and the admin user email can also be changed later using the user interface or Cumulocity API.

Upon successful configuration, the tool will exit automatically.

For a complete list of all supported configurations beyond those described in this section, use the c8yedge config --help command.

Configuring Edge in a self-managed Kubernetes cluster

You can modify the Edge configuration by directly editing a YAML document that represents the Edge custom resource. Refer to Edge custom resource for details of the CR structure and configuration options available.

In the below examples, we assume that the Edge object is called c8yedge and is in the namespace c8yedge. All commands should be executed in the shell of the environment you have installed Edge on.

First, retrieve the current state of the custom resource

kubectl get --namespace=c8yedge edge/c8yedge -o yaml > edge.yaml

Edit this file, referring to Edge custom resource for an exhaustive listing of what could be changed. For example, you might add

  domain: <DOMAIN-NAME>
  licenseKey: <CONTENTS-OF-THE-LICENSE-FILE>
  tlsSecretName: edge-tls-secret

indented under the custom resource’s spec for configuring an SSL certificate for your Edge and giving it a custom domain. Note that the license key must always be valid for the domain name, so any change of domain name should be made simultaneously with a change of license key.

Create a secret edge-tls-secret in the c8yedge namespace with your certificate and private key before applying the changed custom resource.

kubectl create secret tls edge-tls-secret --namespace=c8yedge \
  --cert=./certs/tls.crt \
  --key=./certs/tls.key

Apply the changed custom resource with

kubectl apply -f edge.yaml

If you are comfortable using a text editor installed on the host system, then you can edit the custom resource in place.

kubectl edit --namespace=c8yedge edge/c8yedge

Any changes you make will be applied when you save and exit the editor.

These changes may take some time to complete. See Monitoring changes.

Upgrading Edge

The Edge operator follows the recreate update strategy to upgrade the Edge deployment.

Recreating update strategy is an all-or-nothing process that updates all aspects of the system at once with a brief downtime period. The Edge operator selects all the outdated pods and deactivates them at once. Once all old pods are deactivated, the Edge operator creates updated pods for the entire system. Edge is not operational while the old pods are deactivating and until the final updated pod is created.

Upgrading with the c8yedge tool

You can upgrade to the latest patch of Edge by running the following command:

c8yedge upgrade

This will only apply the latest patches for the current release train. For example, this command will perform an upgrade from 2026.0.3 to 2026.0.5, but not 2026.0.3 to a new major version after 2026. To specify an explicit version to upgrade to:

c8yedge upgrade --version <version number>

Unlike the initial installation, no use of sudo is required for any kind of upgrade using c8yedge.

Upgrading in an airgapped environment

If Edge is now running in an environment with no or limited internet access, you can upgrade by creating an offline package and transferring it to your airgapped environment. See Install Edge in an airgapped environment. There is no difference between a package created for an initial installation, and a package created for an upgrade.

Once in the airgapped environment:

c8yedge upgrade -s c8yedge.tar

Upgrading Edge in a self-managed Kubernetes cluster

Upgrading Edge works similarly to applying a configuration change, with the target version specified as a configuration value. To upgrade to the latest available version from the current release, set the version to "2026". To upgrade to a specific patch version, use a fully qualified version string such as "2026.0.1".

kubectl --namespace=c8yedge patch edge/c8yedge --type=merge -p '{"spec":{"version":"2026"}}'

The operator will also upgrade itself as part of this process. See Monitoring changes to follow the progress of the upgrade.

Upgrading Edge remotely

For information about upgrading Edge remotely, see Upgrading Edge remotely.

Restarting the Edge operator

Run this command to restart the Edge operator.

kubectl rollout restart deployment --namespace=c8yedge c8yedge-operator-controller-manager

Configuring the email server

Configuring an email server enables you to receive email notifications about events, alarms, and also to reset your password. In case you forget the password, the Edge mails you the password reset link to reset your password.

To configure the “reset password” template and email server settings, perform the following steps:

1. Log into the Management tenant using the management domain and administrator credentials created during the installation. For more information on logging in to the Management tenant, see To access Edge

2. Update the email server details and templates as mentioned in Password reset and Email server.

Accessing Edge via an external IP

To get the external IP to access Edge, run the command below:

kubectl get service cumulocity-ontoplb --namespace=c8yedge

Sample output of the kubectl get service command:

NAME              	TYPE           CLUSTER-IP          EXTERNAL-IP         PORT(S)
cumulocity-ontoplb  LoadBalancer   X.X.X.X **REDACTED  X.X.X.X **REDACTED  443:32443/TCP,8443:32442/TCP,1883:32083/TCP,8883:32084/TCP ...

Sometimes the external IP displays as <pending> or <none>. The IP assignment process is dependent on the Kubernetes hosting environment. An external load balancer in the hosting environment handles the IP and port allocation, along with any other configurations necessary to route the external traffic to the Kubernetes service.

Most on-premise Kubernetes clusters do not have external load balancers that can dynamically allocate IPs. The most common solution is to manually assign an external IP to the service. This can be done in the service’s YAML configuration. You can use the following command to manually assign an external IP to the cumulocity-ontoplb service (replace <EXTERNAL-IP> in the command below with the IP address you want to assign).

kubectl patch service cumulocity-ontoplb --namespace=c8yedge -p '{"spec":{"type": "LoadBalancer", "externalIPs":["<EXTERNAL-IP>"]}}'

Even if a load balancer is available, it may be that some of the ports required are already being monopolized by a Kubernetes Ingress provider. For example, Traefik will normally take over ports 80 and 443, and will need to be disabled or reconfigured.

Monitoring changes

Any change that involves an update to the custom resource via kubectl will run and complete in the background. Whether it’s a configuration change or an upgrade, you can use kubectl to monitor the progress of the changes in detail:

kubectl get events --namespace=c8yedge --sort-by=.metadata.creationTimestamp --watch

When it completes successfully, you will see a message of the form Cumulocity Edge installation is complete....

If you are making an update through automated scripting, you can also just wait for the custom resource to advertise itself as Ready after the change:

kubectl wait --timeout=1800s --namespace=c8yedge --for='jsonpath={.status.state}=Ready' edge/c8yedge

This command will return with exit code 0 when the change completes successfully, or a non-zero exit code if it does not complete after the timeout.

Uninstalling Edge

If you have installed Edge using the c8yedge tool, uninstallation is as simple as invoking:

sudo c8yedge uninstall

Otherwise, remove both the Edge Custom Resource and the Edge operator. Assuming the Custom Resource is called c8yedge in the c8yedge namespace:

kubectl delete edge c8yedge --namespace=c8yedge
helm uninstall c8yedge-operator --namespace=c8yedge

Modifying the registry credentials used by Edge

Whether you are using the Edge registry or your own private registry, at some point your credentials on that registry might change. In that case, Edge needs to be updated so that it can access the artifacts for any future upgrade.

These credentials are stored as a secret within the Kubernetes cluster, and can be modified with kubectl commands on the environment in which Edge is installed:

kubectl delete secret docker-registry c8yedge-operator-regcred --namespace=c8yedge
kubectl create secret docker-registry c8yedge-operator-regcred --docker-server=registry.c8y.io --docker-username=<registry username> --docker-password=<registry password> --namespace=c8yedge

If you are using a private registry rather than the Edge registry, simply replace registry.c8y.io with the hostname of your private registry.