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.

Install Edge in an airgapped environment

If you are installing Edge on an environment that has no or limited internet access, you will have to use c8yedge to create an offline package first. This has to be executed in an environment with internet access. Execute the following command and follow the interactive prompts:

c8yedge package

By default, you will get a file out of this called c8yedge.tar in your current directory, containing the latest release of Edge 2025. You can discover more options with c8yedge package --help, such as the ability to package a very specific version.

The offline package can be used for either an initial installation, or an upgrade of an existing installation. You need to transfer this file as well as the c8yedge tool into your airgapped environment.

c8yedge installs Lightweight Kubernetes (K3s), which has prerequisites for running in an airgapped environment. If your environment has no network interface with a default route, or SELinux is enabled, pay attention to and follow the two relevant sections under Prerequisites.

Once in the airgapped environment:

sudo c8yedge install -s c8yedge.tar

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 registry login registry.c8y.io --username="<Edge registry username>" --password="<Edge registry password>"

helm upgrade --install c8yedge-operator oci://registry.c8y.io/edge/helm-charts/cumulocity-iot-edge-operator \
    --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 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.