Managing Edge

Modifying Edge

You can configure and upgrade Edge by making changes to the custom resource (CR), an object in Kubernetes representing this Edge installation. Power users may wish to jump straight in, and refer to Edge custom resource for details of the CR structure and configuration options available.

In these examples, we assume that the Edge object is called c8yedge and is in the namespace c8yedge. This is the case if you have installed Edge using the c8yedge tool, and can be taken verbatim. All commands should be executed in the shell of the environment you have installed Edge on.

Basic post-installation configuration

Immediately post-installation, you will probably want to configure an SSL certificate for your Edge, and give it a custom domain.

First, ensure that your certificate and key are in separate files, in PEM format.

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

Then apply the configuration:

kubectl --namespace=c8yedge patch edge/c8yedge --type=merge -p '{"spec":{"domain":"myown.iot.com", "licenseKey":"...", "tlsSecretName": "edge-tls-secret"}}'

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.

The change may take some time to complete. See Monitoring changes.

More general configuration changes

All configuration options can be accessed simply by editing a YAML document that represents the Edge custom resource. 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 messagingService: true indented under the custom resource’s spec. 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.

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 from Edge version 10.18

Before upgrading Edge to 2025, run the following command to patch the c8yedge-operator-manager-role ClusterRole with the necessary permissions:

kubectl patch clusterrole c8yedge-operator-manager-role --type='json' --patch "$(curl -s https://cumulocity.com/docs/2025/files/edge-k8s/c8yedge-operator-cluster-role-patch-1018.yaml)"

This step is required to ensure the Edge operator can properly enforce validation and mutation rules when updating the Edge CR.

Why this change is needed?

The Edge operator version 2025 leverages the admission webhooks feature of Kubernetes to enhance validation and enforce default configurations for the Edge CR.

• The validating admission webhook ensures that any changes to the Edge CR comply with required constraints.
• The mutating admission webhook automatically applies custom default values where needed.

The Edge operator to leverage the admission webhooks requires additional permissions, which the above command applies.

Starting the upgrade

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 "2025". To upgrade to a specific patch version, use a fully qualified version string such as "2025.0.1".

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

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 allocation and 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>"]}}'

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.

Migrating Edge Appliance VM to Edge 2025

This section outlines the procedure for migrating from Edge appliance VM 10.17 or 10.18 to Edge 2025. Since the Edge 2025 release is installed on Kubernetes, the migration process entails a side-by-side installation accompanied by data migration.

Step 1 - Time series conversion of Edge appliance data

The Cumulocity Operational Store provides an enhanced time series support (so-called time series collections) for measurements data. This configuration is enabled in the Edge 2025, hence you have to first migrate the non time series collections in the Edge appliance VM to time series collections. For more details on time series, refer to enhanced time series support.

Perform the following steps as a root user on your Edge appliance VM to accomplish the time series migration.

1. Set MANAGEMENT_ADMIN_USER and MANAGEMENT_ADMIN_PASSWORD environment variables used in the subsequent commands:

   MANAGEMENT_ADMIN_USER="<MANAGEMENT-ADMIN-USER>"          # Replace with Management tenant admin user
   MANAGEMENT_ADMIN_PASSWORD="<MANAGEMENT-ADMIN-PASSWORD>"  # Replace with Management tenant admin user's password
   
   EDGE_REGISTRY_USER="<EDGE-REGISTRY-USER>"                # Replace with Edge registry username 
   EDGE_REGISTRY_PASSWORD="<EDGE-REGISTRY-PASSWORD>"        # Replace with Edge registry password 
   

   Info

   To request the Edge registry credentials, contact product support.

2. Ensure that the Management tenant admin user you use in this process has the following roles assigned:

   • ROLE_INVENTORY_READ
   • ROLE_OPTION_MANAGEMENT_READ
   • ROLE_OPTION_MANAGEMENT_ADMIN
   • ROLE_TENANT_MANAGEMENT_ADMIN
   • ROLE_APPLICATION_MANAGEMENT_SUBSCRIPTIONS_READ

   ROLES=(
      "ROLE_INVENTORY_READ"
      "ROLE_OPTION_MANAGEMENT_READ"
      "ROLE_OPTION_MANAGEMENT_ADMIN"
      "ROLE_TENANT_MANAGEMENT_ADMIN"
      "ROLE_APPLICATION_MANAGEMENT_SUBSCRIPTIONS_READ"
   )
   for ROLE_ID in "${ROLES[@]}"; do
      echo "Assigning role ${ROLE_ID} to Admin User group"
      curl -k -X POST \
         https://localhost/user/management/groups/2/roles \
         -u "management/${MANAGEMENT_ADMIN_USER}:${MANAGEMENT_ADMIN_PASSWORD}" \
         -H "Accept: application/json" \
         -H "Content-Type: application/vnd.com.nsn.cumulocity.rolereference+json" \
         -d "{\"role\": {\"self\": \"/user/roles/${ROLE_ID}\"}}"
      echo -e "\n"
   done    
   

3. To allow MongoDB to accept both TLS and non-TLS connections, edit the /etc/mongod.conf file and change requireTLS to preferTLS in the net.tls.mode setting, then restart MongoDB with systemctl restart mongod.

4. Install and run the timeseries-migration microservice:

   docker login registry.c8y.io --username "${EDGE_REGISTRY_USER}" --password "${EDGE_REGISTRY_PASSWORD}"
   DOCKER_GATEWAY_IP=$(docker network inspect bridge --format='{{(index .IPAM.Config 0).Gateway}}')
   docker run -d \
      --name timeseries-migration \
      --network bridge \
      -p 8888:8080 \
      -p 8001:8001 \
      -e C8Y_BASEURL=http://${DOCKER_GATEWAY_IP}:8111 \
      -e SPRING_DATA_MONGODB_URI="mongodb://${DOCKER_GATEWAY_IP}:27017/admin" \
      -e C8Y_BOOTSTRAP_TENANT=management \
      -e C8Y_BOOTSTRAP_USER=${MANAGEMENT_ADMIN_USER} \
      -e C8Y_BOOTSTRAP_PASSWORD=${MANAGEMENT_ADMIN_PASSWORD} \
      -e MICROSERVICE_URL=http://${DOCKER_GATEWAY_IP}:8888 \
      registry.c8y.io/platform/timeseries-migration-server:1.0.326
   

5. Follow the container logs using the following command and wait until the message c.s.m.t.TimeseriesMigrationApplicationKt : Started TimeseriesMigrationApplicationKt ... appears.

   docker logs -f timeseries-migration
   

6. Trigger the time series migration:

   curl -k -X PUT \
      https://localhost/service/timeseries-migration/migrations \
      -u "management/${MANAGEMENT_ADMIN_USER}:${MANAGEMENT_ADMIN_PASSWORD}" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{ "state": "SCHEDULED", "tenants": [ "edge" ] }'
   

7. After the data is processed, verified, and migrated to the new collection, the status of the migration changes to VERIFIED:

   curl -k -X GET \
      https://localhost/service/timeseries-migration/migrations/edge \
      -u "management/${MANAGEMENT_ADMIN_USER}:${MANAGEMENT_ADMIN_PASSWORD}" \
      -H "Accept: application/json"
   

   The response returned should contain the migration status as VERIFIED against the Edge tenant.

   Info

   The time to complete the time series conversion and reach VERIFIED status depends on your database size — larger databases require more time to process.

8. Approve the migration to confirm the process:

   curl -k -X PUT \
      https://localhost/service/timeseries-migration/migrations \
      -u "management/${MANAGEMENT_ADMIN_USER}:${MANAGEMENT_ADMIN_PASSWORD}" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{ "state": "APPROVED", "tenants": [ "edge" ] }'
   

   This will change the status of the migration to APPROVED.

9. Check the migration status and wait until it has changed to APPROVED:

   curl -k -X GET \
      https://localhost/service/timeseries-migration/migrations/edge \
      -u "management/${MANAGEMENT_ADMIN_USER}:${MANAGEMENT_ADMIN_PASSWORD}" \
      -H "Accept: application/json"
   

   The response returned should contain the migration status as APPROVED against the Edge tenant.

10. Stop the timeseries-migration microservice:

    docker stop timeseries-migration
    

11. Remove legacy collection:

    mongo \
       --host localhost:27017 \
       edge \
       --eval 'db.pmdata.drop()'
    

Step 2 - Backing up data and configuration of Edge appliance

In your Edge appliance VM, back up the MongoDB data, data lake contents from DataHub if present.

Perform the following steps as a root user on your Edge appliance.

1. Unmonitor and stop all services except the mongod service:

   monit unmonitor all && \
   systemctl stop installation-service opcua-mgmt-service opcua-device-gateway smartrule apama cumulocity-core-karaf
   

2. If you have installed Cumulocity DataHub in the Edge appliance, stop the cdh-console, cdh-master and cdh-executor services:

   service cdh-console stop && \
   service cdh-master stop && \
   service cdh-executor stop
   

3. Export the MongoDB data using mongodump utility:

   mongodump \
      --host localhost:27017 \
      --db management \
      --out=/opt/appliance-edgedb-backup
   

   mongodump \
      --host localhost:27017 \
      --db edge \
      --out=/opt/appliance-edgedb-backup
   

4. Tar the MongoDB data and data lake contents from DataHub if present, into /opt/edge-appliance-backup.tar :

   tar -zcf /opt/edge-appliance-backup.tar /opt/appliance-edgedb-backup /opt/softwareag
   

5. After creating the /opt/edge-appliance-backup.tar file, copy it to a network drive or storage location that is accessible from the machine on which you will install Edge 2025 in the next step. Once the backup file is safely stored, shut down the Edge appliance to prevent any further changes to the system during the migration process. This step is optional, and if not performed, you must copy the backup file into the target machine once it is created.

Step 3 - Install Edge 2025

Follow the steps documented at Installing Edge to install and configure Edge 2025.

After installing Edge 2025, configure the Edge domain and license to match those of the Edge Appliance VM you are migrating. For details, refer to Modifying Edge

Step 4 - Restore MongoDB data from the backup

After installing and configuring Edge 2025, proceed to migrate the data backed up from the Edge Appliance VM.

1. Transfer the backup file /opt/edge-appliance-backup.tar from the Edge Appliance VM to your Edge 2025.

2. Untar the backup file:

   tar -xf /opt/edge-appliance-backup.tar -C /
   

3. Restore the MongoDB data. This step deploys a pod named edge-appliance-migration:

   curl -sfL https://cumulocity.com/docs/2025/files/edge-k8s/c8yedge-appliance-migration-db-restore.sh -O && bash ./c8yedge-appliance-migration-db-restore.sh
   

   Then, monitor the logs using the command below. Wait until the message >> Edge DB restore finished. appears before proceeding to the next step:

   kubectl logs -f pod/edge-appliance-migration -n c8yedge
   

4. Restart Edge:

   kubectl rollout restart deployment -n c8yedge c8yedge-operator-controller-manager
   

   Ensure you are able to access Edge before continuing with the subsequent steps.

5. Remove the /opt/edge-appliance-backup.tar and /opt/appliance-edgedb-backup folders:

   rm -rf /opt/appliance-edgedb-backup /opt/edge-appliance-backup.tar
   

Step 5 - Configuring Edge 2025 post migration

After successfully migrating your data to Edge 2025, you’ll need to configure it to match your previous Edge Appliance VM setup. Here’s what you need to do:

What’s already available?

The following components from your Edge tenant are automatically retained in Edge 2025:

• Web SDK-based applications and plugins
• Dashboards and widgets
• Smart rules
• Analytics Builder models and Apama Event Processing Language (EPL) apps
• Branding

What needs to be re-uploaded?

• From your Edge tenant
  • Custom microservices
• From your Management tenant
  • Custom microservices
  • Web SDK-based applications and plugins
  • Dashboards and widgets
  • Smart rules
  • Analytics Builder models and Apama Event Processing Language (EPL) apps
  • Branding

Connecting Edge to the cloud

If your previous Edge Appliance VM was connected to the cloud, you’ll need to set up this connection again in Edge 2025. Follow the guide: Connecting Edge to the cloud

Uninstalling Edge

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

sudo c8yedge uninstall

For a kubernetes-native install, 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.