Installation

Prerequisites

Domain name validation for Edge license key generation

To procure the Edge license, you must provide the right domain name to product support for Edge license key generation.

When you provide the domain name, consider the following points:

• The domain name does not need to be a Fully Qualified Domain Name (FQDN). For example, to access Edge with the domain name myown.iot.com, request the Edge license for myown.iot.com or iot.com (without the subdomain myown).

• If you exclude the subdomain from the domain name in the Edge license, you must possess a wildcard SSL certificate which can be used with multiple subdomains (myown or others) of the domain (iot.com).
  For example, if you provide iot.com as the domain name, you must possess an SSL certificate for .iot.com.

• If you have an Internationalized Domain Name (IDN), then you must provide the translated ASCII equivalent domain name.
  For example, if your domain name is myown.iöt.com (for example, containing ö), then you must use myown.xn–it-fka.com.
  Also, provide the same translated ASCII equivalent domain name as the tenant domain name during the Edge installation process.
  

  Info

  An Internationalized Domain Name (IDN) is an internet domain name that contains at least one label, in whole or in part, in a language-specific script or alphabet, such as Arabic, Chinese, Cyrillic, Devanagari, Hebrew or the Latin alphabet-based characters with diacritics or ligatures, such as French. The internationalization of domain names is a technical solution to translate names written in language-native scripts into an ASCII text representation that is compatible with the Domain Name System. See Wikipedia.

• Ensure that you adhere to the following domain name validation rules:

  • The domain name must be a combination of case-insensitive alphanumeric characters separated by dot ( . ) or hyphen ( - ).
    • Cannot contain any letters of languages like Chinese, Latin or Arabic.
    • Cannot contain any special characters like (+ , ! @ # $ % ^ & * ( ) ; \ \ / | < > \ " \ ’ ) other than dot ( . ) or hyphen ( - ).
  • The length of the domain name including the dot must not exceed 255 characters.
  • The domain name must contain at least one dot.
  • Each segment of the domain name must be separated by a dot.
    • The domain name must be between 1 to 63 characters long.
    • The Top-Level Domain (TLD) which refers to the last segment of the domain name must be between two to six characters long.
    • The domain name cannot begin or end with a hyphen.

Installing with the c8yedge tool

This method is ideal if you do not already have a Kubernetes cluster and want a simplified, self-contained setup. The c8yedge command-line tool automates the entire process of preparing the environment and installing Edge on a Linux environment.

Configuring the environment

Edge can be installed on any modern x86-64 Linux environment, virtualised or otherwise.

First, choose your environment. It can be a physical machine, or it can be a virtual machine (VM), using the technology of your choice. For example, VMWare Workstation Player, VMWare ESXi or HyperV. Create a VM, referring to the documentation from your VM technology vendor as necessary.

Whether a VM or physical machine, ensure that all hardware and storage requirements for Edge are met, based on prerequisites.

Install the Linux distribution of your choice. Because the c8yedge-based install provisions Edge on Lightweight Kubernetes (K3s), you should consult the operating system configurations required by K3s to help you choose and configure your operating system.

Downloading c8yedge

You can download the tool from the Cumulocity Download Center or by running the following commands:

curl -sfL https://download.cumulocity.com/Cumulocity-Edge/Installer/2025/c8yedge -o c8yedge
sudo chmod +x c8yedge
sudo mv c8yedge /usr/local/bin/

The tool takes commands of the form

sudo c8yedge [command] [flags]

For more information about the tool, run c8yedge --help or c8yedge [command] --help.

Install Edge

To install Edge, execute the following command and follow the interactive prompts:

sudo c8yedge install

Upon successful installation, the tool will exit automatically.

To sign in to Edge, refer to the instructions at the start of the Accessing Edge section. You can later update the domain and license to match your environment by following the steps outlined in Modifying Edge.

Installing with the Kubernetes-native approach

This method is suitable for users who already have a Kubernetes cluster and want to install Edge using the Kubernetes-native approach. Before you start the installation, ensure that you have met the prerequisites and configured the storage as described in Configuring storage.

You will need Helm version 3.x available on your system. Refer to Installing Helm for the installation instructions.

Installing the Edge operator

The Edge operator is available as a Helm chart in the Edge registry, and can be installed like any other chart. You will need your registry credentials, which can be acquired from product support. Assuming you are installing the 2025 release of Edge, and that you wish all Edge workloads to be running in the namespace c8yedge, run the following command:

helm upgrade --install c8yedge-operator oci://registry.c8y.io/edge/helm-charts/cumulocity-iot-edge-operator \
    --username="<Edge registry username>" --password="<Edge registry password>" \
    --version=2025 \
    --namespace c8yedge \
    --create-namespace \
    --set imageCredentials.username="<Edge registry username>" \
    --set imageCredentials.password="<Edge registry password>" \
    --wait

Run the following command to follow the logs for the Edge operator pod:

kubectl logs -f -n c8yedge deployment/c8yedge-operator-controller-manager manager

Installing the Edge operator (offline)

Frequently, portions of a data center might not have access to the Internet, even via proxy servers. You can still install Edge in such an environment, but you must make the required software, Helm Charts and Docker images, available to the disconnected environment through an Open Container Initiative (OCI) compliant private registry.

To enable this, you need to have an OCI compliant registry available in the network which is accessible to the Kubernetes cluster in which you intend to install Edge. You would also need a workstation that has full internet access, to pull the required software from the Cumulocity registry and push them into the private registry installed or available in the restricted network.

Installing a private registry

Any OCI compliant registry can be used as a private registry, however, the Edge installation is tested with Harbor and Nexus Repository OSS.

Refer to Harbor Installation and Configuration for installing Harbor and Nexus Installation and Upgrades for installing Nexus.

After installing and configuring a private registry, ensure that all the machines (the workstation and the Kubernetes cluster nodes) which need access to the private registry can resolve its domain or host and trust the private registry’s certificate (if it is configured with a self-signed certificate).

Update /etc/hosts to resolve the domain

Run the below commands to update the /etc/hosts file on every machine (the workstation and the Kubernetes cluster nodes) which needs access to the private registry can resolve its domain or host:

PRIVATE_REGISTRY_HOSTNAME="<PRIVATE-REGISTRY-HOSTNAME>"  	# Change it with your private registry's domain or hostname
PRIVATE_REGISTRY_IP_ADDRESS="<PRIVATE-REGISTRY-IP-ADDRESS>" # Change it with your private registry's IP Address

# Update /etc/hosts to resolve the Harbor domain
echo "${PRIVATE_REGISTRY_IP_ADDRESS} ${PRIVATE_REGISTRY_HOSTNAME}" | sudo tee -a /etc/hosts

Update CoreDNS configuration

Run the commands below to extend the CoreDNS configuration of the Kubernetes cluster to enable resolution of the private registry’s domain or host:

PRIVATE_REGISTRY_HOSTNAME="<PRIVATE-REGISTRY-HOSTNAME>"  	# Change it with your private registry's domain or hostname
PRIVATE_REGISTRY_IP_ADDRESS="<PRIVATE-REGISTRY-IP-ADDRESS>" # Change it with your private registry's IP Address

# Uses the hosts plugin to resolve the private registry's domain or hostname to its IP address
# The [fallthrough] directive allows the query to continue to the next server block if the name doesn’t match
COREDNS_CUSTOM_CONFIGMAP_NAME="coredns-custom"
KUBE_SYSTEM_NAMESPACE="kube-system"
KEY_NAME="private-registry.server"
KEY_VALUE=$(cat <<EOF
${PRIVATE_REGISTRY_HOSTNAME}:53 {
  hosts {
    ${PRIVATE_REGISTRY_IP_ADDRESS} ${PRIVATE_REGISTRY_HOSTNAME}
    fallthrough
  }
}
EOF
)

# Create or Patch the 'coredns-custom' ConfigMap
if ! kubectl get configmap "$COREDNS_CUSTOM_CONFIGMAP_NAME" -n "$KUBE_SYSTEM_NAMESPACE" >/dev/null 2>&1; then
  # Create the configmap
  kubectl create configmap "$COREDNS_CUSTOM_CONFIGMAP_NAME" -n "$KUBE_SYSTEM_NAMESPACE" \
    --from-literal="$KEY_NAME=$KEY_VALUE"
else
  # Patch the configmap
  kubectl patch configmap "$COREDNS_CUSTOM_CONFIGMAP_NAME" \
    -n "$KUBE_SYSTEM_NAMESPACE" --type merge \
    -p "{\"data\": {\"$KEY_NAME\": \"$(echo "$KEY_VALUE" | sed ':a;N;$!ba;s/\n/\\n/g')\"}}"
fi

# Restart CoreDNS Deployment to apply changes
kubectl rollout restart deployment coredns -n kube-system

# Wait until CoreDNS pods are ready
kubectl rollout status deployment coredns -n kube-system

Trust the private registry’s certificate

Run the below commands to trust the private regsitry’s certificate (if it is configured with a self-signed certificate), on every machine (the workstation and the Kubernetes cluster nodes) which needs access to the private registry including the Kubernetes cluster nodes:

sudo sh -c '
PRIVATE_REGISTRY_HOST="<PRIVATE-REGISTRY-HOSTNAME>:<PRIVATE-REGISTRY-PORT>"  # Change it with your private registry domain or hostname:port or ip-address:port

PRIVATE_REGISTRY_CA_CERT=$(echo quit | openssl s_client -showcerts -servername ${PRIVATE_REGISTRY_HOST} -connect ${PRIVATE_REGISTRY_HOST}) && \
if command -v "update-ca-certificates" > /dev/null 2>&1; then
	mkdir -p /usr/local/share/ca-certificates
	echo "${PRIVATE_REGISTRY_CA_CERT}" > /usr/local/share/ca-certificates/private-registry-ca.crt
	update-ca-certificates
elif command -v "update-ca-trust" > /dev/null 2>&1; then
	mkdir -p /etc/pki/tls/certs
	echo "${PRIVATE_REGISTRY_CA_CERT}" > /etc/pki/tls/certs/private-registry-ca.crt
	update-ca-trust extract
fi
'

Download and publish required software to the private registry

This section outlines the steps to download the required software from the Cumulocity registry and publish them to the private registry.

For this you need a workstation with full internet access to download the required software from the remote registry and push them into the private registry. Make sure this workstation meets the following prerequisites.

Install registry sync script

To install registry synchronization script, run the commands below:

pip install --force-reinstall https://download.cumulocity.com/Cumulocity-Edge/Installer/2025/c8yedge_registry_sync-2025-py3-none-any.whl

Run registry sync script

To download the required software from the Cumulocity registry and publish them to the private registry, run the command below:

EDGE_REGISTRY_USER="<EDGE-REGISTRY-USER>"     	# Edge registry credentials can be obtained from the Cumulocity logistics team for your region
EDGE_REGISTRY_PASSWORD="<EDGE-REGISTRY-PASS>" 	# Edge registry credentials can be obtained from the Cumulocity logistics team for your region

PRIVATE_REGISTRY_HOST="<PRIVATE-REGISTRY-HOSTNAME>:<PRIVATE-REGISTRY-PORT>"  # Change it with your private registry domain or hostname:port or ip-address:port
PRIVATE_REGISTRY_USERNAME="<PRIVATE-REGISTRY-USER>"                          # Change it with the credentials to access your private registry
PRIVATE_REGISTRY_PASSWORD="<PRIVATE-REGISTRY-PASSWORD>"                      # Change it with the credentials to access your private registry

c8yedge_registry_sync sync -v 2025 -sr registry.c8y.io -sru "${EDGE_REGISTRY_USER}" -srp "${EDGE_REGISTRY_PASSWORD}" -tr "${PRIVATE_REGISTRY_HOST}" -tru "${PRIVATE_REGISTRY_USERNAME}" -trp "${PRIVATE_REGISTRY_PASSWORD}" --dryrun False

Update custom-environment-variables ConfigMap

Run the below commands to create or update the custom-environment-variables ConfigMap with key “ca.crt” for the Edge operator to trust the private registry’s certificate (if it is configured with a self-signed certificate):

EDGE_NAMESPACE=c8yedge                    									 # Change namespace name if you want to deploy Edge operator and Edge in a different namespace

PRIVATE_REGISTRY_HOST="<PRIVATE-REGISTRY-HOSTNAME>:<PRIVATE-REGISTRY-PORT>"  # Change it with your private registry domain or hostname:port or ip-address:port

PRIVATE_REGISTRY_CA_CERT=$(echo quit | openssl s_client -showcerts -servername ${PRIVATE_REGISTRY_HOST} -connect ${PRIVATE_REGISTRY_HOST})
mkdir -p /tmp
echo "${PRIVATE_REGISTRY_CA_CERT}" > /tmp/private-registry-ca.crt

# Create/Update custom-environment-variables ConfigMap with key "ca.crt" for the edge operator to trust
kubectl create namespace "${EDGE_NAMESPACE}" --dry-run=client -o yaml | kubectl apply -f -
kubectl create configmap custom-environment-variables -n "${EDGE_NAMESPACE}" --from-file=ca.crt="/tmp/private-registry-ca.crt" --dry-run=client -o yaml | kubectl apply -f -

Installing the Edge operator

Continue with installing the Edge operator by following the instructions in Installing the Edge operator passing the private registry’s host (-r option) as <private-registry-hostname>:<private-registry-port> and the respective registry credentials when prompted.

Installing Edge

Download and edit the Edge CR (c8yedge.yaml), before applying it to your Kubernetes cluster by running the command below:

kubectl apply -f c8yedge.yaml

This command will complete immediately, and the installation will proceed in the background. See Monitoring changes to track the progress of the installation.

For more information about the structure and configuration options available in the Edge CR, see Edge custom resource.

Configuring storage

Kubernetes makes physical storage devices available to your cluster in the form of two API resources, PersistentVolume and PersistentVolumeClaim.

A Persistent Volume (PV) is a storage resource in Kubernetes that is provisioned and managed independently from the Pods that use it. It provides a way to store data in a durable and persistent manner, even if the Pod that uses it is deleted or restarted.

PVs are typically used to store data that must be preserved across Pod restarts or rescheduling, such as databases or file systems. They can be backed by various storage technologies, such as local disks, network-attached storage (NAS), or cloud-based storage services.

To use a PV in Kubernetes, you must define a PersistentVolume object that describes the characteristics of the storage, such as capacity, access modes, and the storage-provider-specific details. Once the PV is created, you can create a PersistentVolumeClaim object that requests a specific amount of storage with specific access requirements. The Persistent Volume Claim (PVC) binds to a matching PV, and the Pod can then use the PVC to mount the storage and access the data.

By using PVs and PVCs, you can decouple the storage management from the application deployment, making it easier to manage and scale your applications in Kubernetes.

PVs represent cluster resources, while PVCs serve as requests for these resources and also serve as validation checks for the resource they request. Provisioning PVs can be done in two ways: statically or dynamically.

• Static provisioning: In this method, a cluster administrator manually creates PVs, specifying details about the actual storage available for cluster users. These PVs are registered in the Kubernetes API and are ready for consumption.

• Dynamic provisioning: When none of the statically created PVs match a PVC’s requirements, the cluster can automatically provision storage on-demand, specifically tailored for the PVC. This dynamic provisioning relies on StorageClasses. To trigger dynamic provisioning, the PVC must request a StorageClass, and the administrator must have set up and configured that class accordingly. Claims that request an empty string (“”) for the class effectively disable dynamic provisioning for themselves. If no StorageClass is specified in a claim, it falls back to using a default StorageClass if one is configured in the cluster. To enable a default StorageClass, the cluster administrator must activate the DefaultStorageClass admission controller on the API server. This can be achieved, for instance, by ensuring that DefaultStorageClass is included in the comma-delimited, ordered list of values for the –enable-admission-plugins flag of the API server component. For more details on API server command-line flags, refer to the kube-apiserver documentation.

Persistent Volume Claims made by the Edge operator

The Edge operator requests three PVCs, as outlined in the table below. Each of these PVCs utilizes the StorageClass if specified within the spec.storageClassName field of the Edge CR.

• In case you omit the spec.storageClassName, the Edge operator requests PVCs without a StorageClass, thereby instructing Kubernetes to utilize the default StorageClass configured in the cluster.

• If you explicitly specify an empty StorageClass as "", the Edge operator requests PVCs with an empty StorageClass, thereby instructing Kubernetes to carry out static provisioning.

• Finally, if you specify the name of an existing StorageClass for which dynamic provisioning is enabled, the Operator requests PVCs with that class name, thereby instructing Kubernetes to utilize dynamic provisioning according to the specified class.

To guarantee the retention of physical storage even after the PVC is deleted (for example, when Edge is deleted) and to enable future storage expansion if needed, it’s crucial to configure the StorageClass and/or the PVs with the following settings:

1. Reclaim Policy: Ensure that the reclaim policy is set to Retain. This setting preserves the storage even after the PVC deletion.
2. Volume Expansion: Set the volume expansion option to true. This setting enables the storage to be expanded when necessary.

Kubernetes provides a variety of persistent volume types, but two specific types enable Pod containers to access either a Network File System (NFS) or the cluster node’s local filesystem (often set up as a NFS drive mapped to a local folder). This configuration is especially prevalent in on-premises deployments.

Static provisioning of PVs

This section outlines the steps for configuring the Kubernetes cluster to enable Edge to utilize NFS as a source for the PVs. For additional storage options, refer to the Kubernetes documentation.

• Storage provisioning by connecting directly to the NFS server via PV configuration

  • Download the c8yedge-pv-nfs.yaml file.

  • Create and export the folders required for the 3 PVs defined in the c8yedge-pv-nfs.yaml file. Ensure that the user running Kubernetes server has read/write access to these folders.

  • Run the command below:

    kubectl apply -f c8yedge-pv-nfs.yaml
    

• Storage provisioning by mapping NFS drive to a local folder into the cluster node

  • Download the c8yedge-pv-local-path.yaml file.

  • Create the folders in the local file system or mount NFS folders required for the 3 PVs defined in the c8yedge-pv-local-path.yaml file. Ensure that the user running Kubernetes server has read/write access to these folders.

  • Run the command below:

    kubectl apply -f c8yedge-pv-local-path.yaml
    

Configuring proxy

When Cumulocity Edge is deployed behind a proxy, it must be configured to communicate with external endpoints over the internet through the proxy server. To configure Edge to use a proxy, you must create or update a ConfigMap named custom-environment-variables in the c8yedge namespace (or the one you deployed Edge into) with the required proxy settings. The keys http_proxy, https_proxy and socks_proxy must be set to the URLs of the HTTP, HTTPS and Socks proxies, respectively. The key no_proxy must be set to specify a comma-separated list of domain suffixes, IP addresses, or CIDR ranges that Edge should bypass the proxy server for.

Here is an example of a ConfigMap with proxy settings:

##
## An optional ConfigMap to configure the Edge operator with
##    - Proxy details when accessing external endpoints through a Proxy
##    - TLS/SSL certificates to trust
##
## http_proxy, https_proxy and optionally socks_proxy must be configured with the relevant URLs.
## no_proxy must be configured with a comma-separated list of addresses or domains for which the proxy should be bypassed.
##

apiVersion: v1
kind: ConfigMap
metadata:
  ## The name is fixed and cannot be changed.
  name: custom-environment-variables
  ## Namespace name into which you installed the Edge operator.
  namespace: c8yedge
data:
  http_proxy: <HTTP Proxy URL>
  https_proxy: <HTTPS Proxy URL>
  socks_proxy: <SOCKS Proxy URL>

  ## A comma-separated list of addresses or domains for which the proxy will be bypassed.
  ## This must be configured with the specified entries, Edge domain name, Kubernetes Pod CIDR (Cluster Pod IP Address Range), 
  ## Kubernetes Service CIDR (Cluster Service IP Address Range) and any other domains, hosts or IPs 
  ## you want to bypass the proxy when accessed.
  no_proxy: 127.0.0.1,::1,localhost,.svc,.cluster.local,cumulocity,<edge domain name, for example, myown.iot.com>,<kubernetes cluster IP range, for example, 10.43.0.0/16>

  ## TLS/SSL certificates in PEM format that the Edge operator can trust, in addition to those included in the default system trust store.
  ## You can provide multiple TLS/SSL certificates for trust by combining them into a single string.
  ca.crt: <CA-CERTIFICATES TO TRUST>

By configuring Edge with the appropriate proxy settings, you ensure that it can seamlessly communicate with external endpoints through the proxy server, allowing it to function effectively in environments where proxy usage is mandated.

The table below provides more information:

Accessing Edge

If you have installed Edge on your local machine, then you should be able to immediately access Edge in your browser with the URL http://localhost. If it is on a remote machine or a VM with a simple network setup and no firewall in the way, you can use http://<IP of remote machine or VM>.

When signing into Edge this way, you will be prompted for the Cumulocity tenant id you are signing into. Edge has two tenants, management and edge. When signing in for the first time, use the default credentials username “admin” and password “admin-pass”. If you have installed using the c8yedge tool, the email address will have been initially configured to company@edgebootstrap.example which you will also need when signing in for the first time. These credentials are set for both Cumulocity tenants, and should be changed on both even if you do not intend to use the management tenant.

Accessing Edge using the domain name

Access Edge using the domain name configured as part of the installation. There are two ways of configuring the accessibility with the domain names:

• Add an entry of the domain name and IP address mapping in the DNS servers.
  For example, if your domain name is myown.iot.com, add an entry for both myown.iot.com and management-myown.iot.com.
  
• Alternatively, Add the alias to access Edge through the domain name provided during installation. This must be performed on each client host on which Edge is accessed.

The first option is always preferable so that Edge is accessible over LAN.

Adding the alias

On Linux machines, add the following entry to /etc/hosts:

<IP address> <domain_name>
<IP address> management-<domain_name>

If you do not know the external IP address of your host, see Accessing Edge via an external IP.

On Windows machines, add the same entry to C:\Windows\System32\drivers\etc\hosts.

Ping the <domain_name> to verify it.

ping <domain_name>
ping management-<domain_name>

If the ping is successful, the DNS resolution is working properly.

To access Edge

To access Edge, enter one of the following URLs in the browser:

• For the “edge” tenant, use the URL https://<domain_name>.
• For the Management tenant, use the URL https://management-<domain_name>.

This will bring up the below login screen. Enter the default credentials username “admin” and password “admin-pass” to log in in to both the “edge” tenant and the Management tenant.

On the first login, you see the dialog window below, forcing you to change the password. The email address to change the password is the one you specified in the Cumulocity Edge CR (or company@edgebootstrap.example if you followed the Quickstart installation steps). Alternatively, run the following command to retrieve the email address:

kubectl get edge c8yedge -n c8yedge -o jsonpath='{.spec.email}' && echo

If you are logging in for the first time, you will see a cookie banner at the bottom of the login screen:

• Click Agree and Proceed to accept the default cookie settings (required and functional cookies enabled).
• Click Reject all to reject all of the default cookie settings.
• Click Preferences to select your individual cookie preferences:
  • Required - Required to enable core site functionality. They perform a task or operation without which a site’s functionality would not be possible. Required cookies cannot be disabled.
  • Functional - Used to track site usage and to process personal data to measure and improve usability and performance. Functional cookies must be actively enabled.
• Click See also our Privacy Notice to open the Cumulocity privacy statement with details on the Cumulocity privacy policy.

Select the Remember me checkbox if you want the browser to remember your credentials, so that you do not have to enter them again when opening the application the next time. This is especially convenient if you frequently switch between Cumulocity applications, as Edge requests you to authenticate each time when starting an application. You can make the browser “forget” your credentials by explicitly logging out.

Finally, click Login to enter Edge. Initially, you will be taken to the Cockpit application, if not configured differently. For further information about the Cumulocity standard applications see Available applications.

To explicitly log out, click the User button at the right of the top bar, then select Logout from the context menu.

How to reset or change your password

To reset your password, you must first configure the “reset password” template and email server settings in Edge. For information about configuring the email server, see Configuring the email server.

For information about changing the password, see To change your password.

How to access pages using URLs

For information about accessing pages using the URLs, see URL.