Edge custom resource

This section describes the structure and configuration options available in the Cumulocity Edge CR. Here is the Edge CR template (c8yedge.yaml) that you can edit and apply to your Kubernetes cluster to install or update Cumulocity Edge.

Configuration

The initial part of the CR defines the CRD details, and the CR name and namespace, which referred to in this document as EDGE-CR-NAME and EDGE-CR-NAMESPACE.

apiVersion: edge.cumulocity.com/v1  
kind: CumulocityIoTEdge
metadata:
  name: <EDGE-CR-NAME>
  namespace: <EDGE-CR-NAMESPACE>

Specification

This section defines the Edge deployment’s configurations.

Field	Required	Type	Default	Description
version	Yes	String		Edge version to install. Specify `"2026"` to install the latest available version from the release, or use a fully qualified version like `"2026.0.1"` to install a specific patch version.
domain	Yes	String		A fully qualified domain name. For example, myown.iot.com. Here, you must have the Edge license for the domain name iot.com or myown.iot.com.
licenseKey	Yes	String		Edge license key you received for the domain. To request the license file for Edge, contact product support In the email, you must include - Your company name, under which the license has been bought - The domain name (for example, myown.iot.com), where Edge will be reachable For more information, see Domain name validation for Edge license key generation.
company	Yes	String		Name of the “edge” tenant, for example, the company’s name. Info: This value is used only during the Edge installation and can’t be changed for existing installations. All subsequent tenant changes are made via the user interface or the Cumulocity API.
tlsSecretName	No	String	The Edge operator generates and assigns self-signed TLS/SSL private key and certificates.	Name of the Kubernetes secret containing the TLS/SSL private key and certificates for the domain name specified in the `spec.domain` field. This secret must contain two keys: - tls.key: TLS/SSL private key in the PEM format. Generate a TLS/SSL key pair and a Certificate Signing Request (CSR) following your organization’s policies, specifying either a wildcard domain in the Common Name (CN) (for example, *.iot.com) or listing required domains in the Subject Alternative Name (SAN) field, including the Edge tenant and Management tenant tenant domains (for example, myown.iot.com, management-myown.iot.com). - tls.crt: The TLS/SSL certificate chain associated with the private key in PEM format. It’s essential to ensure the certificates are arranged in the correct sequence for TLS/SSL validation to succeed. The proper order of the certificate chain is: - End-entity certificate: This is the TLS/SSL certificate issued to your domain or server, sometimes referred to as the “leaf” or “server” certificate. - Intermediate certificate(s): These certificates link your end-entity certificate to the trusted root certificate. If there are multiple intermediate certificates, they must be ordered correctly as well. - Root CA certificate: This is the certificate for the Certificate Authority (CA) that is trusted by browsers and other clients. It’s generally included last in the chain. For more information, see TLS/SSL Secret. Info: The Edge operator retrieves this secret from the EDGE-CR-NAMESPACE. Ensure that this secret is created before initiating the Edge deployment or update process.
email	Yes	String		Email used for the admin user. Info: This value is used only during the Edge installation and can’t be changed for existing installations. All subsequent admin user changes are made via the user interface or the Cumulocity API.
cumulocityPasswordSecretName	Yes	String		Name of the Kubernetes secret containing the Cumulocity admin user password for both the Management tenant and the Edge tenant. This secret must contain a key named `INITIAL_C8Y_ADMIN_PASSWORD` with the initial password. For more information, see Cumulocity password secret. Info: The Edge operator retrieves this secret from the EDGE-CR-NAMESPACE. Ensure that this secret is created before initiating the Edge deployment process. Info: This value is used only during the Edge installation and can’t be changed for existing installations. All subsequent password changes are made via the user interface or the Cumulocity API.
cloudTenant	No	Structure		Cumulocity cloud tenant details to configure and manage Edge remotely. For more information, see Cloud Tenant.
storageClassName	No	String		The Edge operator requests three PVCs, as outlined below. - 75 GB, PVC named `mongod-data-edge-db-rs0-0` made by MongoDB server for persisting application data. 75 GB is the default, and its value can be configured through the Edge CR field `spec.mongodb.resources.requests.storage`. - 10 GB, PVC named `microservices-registry-data` made by the private registry for persisting microservice images. - 5 GB, PVC named `edge-logs` made by the Edge logging component for persisting application and system logs. Each of these PVCs utilizes the StorageClass if specified within the `storageClassName` field of the Edge CR. - In case you omit the `storageClassName`, the Edge operator requests PVCs without a StorageClass, thereby instructing Kubernetes to utilize the default StorageClass configured in the cluster. - 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. Info: This value is used only during the Edge installation and can’t be changed for existing installations.
core	No	Structure		Cumulocity platform configurations. For more information, see Cumulocity Core configurations.
mongodb	No	Structure		Configurations needed to deploy the MongoDB server. For more information, see MongoDB.
microservices	No	Array of Structure	The Edge operator deploys all the default Cumulocity microservices, which include the Apama, Smart Rules, OPCUA Management Server and microservice-based data broker microservices.	Specify resources to allocate to each of the default Cumulocity microservices deployed. For more information, see Microservices.

TLS/SSL secret

Specifies the Kubernetes secret containing the TLS/SSL private key and certificate chain. The Edge operator retrieves this secret from the EDGE-CR-NAMESPACE. Ensure that the secret is created before initiating the Edge deployment or update process.

This secret should contain the fields described in the table below.

Field	Required	Type	Default	Description
tls.key	Yes	String		TLS/SSL private key in the PEM format.
tls.crt	Yes	String		The TLS/SSL certificate chain associated with the private key in PEM format. It’s essential to ensure the certificates are arranged in the correct sequence for TLS/SSL validation to succeed. The proper order of the certificate chain is: - End-entity certificate: This is the TLS/SSL certificate issued to your domain or server, sometimes referred to as the “leaf” or “server” certificate. - Intermediate certificate(s): These certificates link your end-entity certificate to the trusted root certificate. If there are multiple intermediate certificates, they must be ordered correctly as well. - Root CA certificate: This is the certificate for the Certificate Authority (CA) that is trusted by browsers and other clients. It’s generally included last in the chain.

Field

Required

Type

Default

Description

tls.key

Yes

String

TLS/SSL private key in the PEM format.

tls.crt

Yes

String

The TLS/SSL certificate chain associated with the private key in PEM format. It’s essential to ensure the certificates are arranged in the correct sequence for TLS/SSL validation to succeed. The proper order of the certificate chain is:

- End-entity certificate: This is the TLS/SSL certificate issued to your domain or server, sometimes referred to as the “leaf” or “server” certificate.

- Intermediate certificate(s): These certificates link your end-entity certificate to the trusted root certificate. If there are multiple intermediate certificates, they must be ordered correctly as well.

- Root CA certificate: This is the certificate for the Certificate Authority (CA) that is trusted by browsers and other clients. It’s generally included last in the chain.

Cumulocity password secret

The Cumulocity password secret specifies the Kubernetes secret containing the initial Cumulocity admin user password. The Edge operator retrieves this secret from the namespace EDGE-CR-NAMESPACE. It is important that this secret is created before initiating the Edge deployment process.

Info

Any changes to the content of this secret after the initial installation of Edge are ignored. Refer to Managing users for updating the Cumulocity admin user password.

This secret should contain the field described in the table below:

Field	Required	Type	Default	Description
INITIAL_C8Y_ADMIN_PASSWORD	Yes	String		Password used to initialize the Cumulocity admin user for both the Management tenant and the Edge tenants. Important: The password must be at least 8 letters long.

Field

Required

Type

Default

Description

INITIAL_C8Y_ADMIN_PASSWORD

Yes

String

Password used to initialize the Cumulocity admin user for both the Management tenant and the Edge tenants.

Important: The password must be at least 8 letters long.

Cloud tenant

Edge can be managed, configured, and monitored remotely through a Cumulocity cloud tenant. You can control and troubleshoot your Edge deployments remotely.

To enable this, you must first register Edge as a device within the cloud tenant. This registration process requires providing the Cumulocity cloud tenant URI, along with an optional TLS/SSL key and certificate chain. These credentials authenticate Edge when connecting to the cloud via the MQTT protocol using X.509 certificate-based authentication.

See Registering Edge in the cloud tenant for more details.

Field	Required	Type	Default	Description
domain	Yes	String		Cumulocity cloud tenant domain. For example, `<tenantid>.cumulocity.com`
tlsSecretName	No	string	The Edge operator generates and assigns self-signed TLS/SSL private key and certificates.	Name of the Kubernetes secret containing the TLS/SSL private key and certificates with which Edge connects to the cloud through MQTT protocol using a X.509 certificate for authentication. This secret must contain two keys: - tls.key: TLS/SSL private key in the PEM format. - tls.crt: The TLS/SSL certificate chain associated with the private key in PEM format. It’s essential to ensure the certificates are arranged in the correct sequence for TLS/SSL validation to succeed. The proper order of the certificate chain is: - End-entity certificate: This is the TLS/SSL certificate issued to your domain or server, sometimes referred to as the “leaf” or “server” certificate. - Intermediate certificate(s): These certificates link your end-entity certificate to the trusted root certificate. If there are multiple intermediate certificates, they must be ordered correctly as well. - Root CA certificate: This is the certificate for the Certificate Authority (CA) that is trusted by browsers and other clients. It’s generally included last in the chain. Info: You can also reuse the secret name provided in the `spec.tlsSecretName` provided that the TLS/SSL certificate it references is issued by an intermediate Certificate Authority (CA) within your organization and can be added to the trusted certificate list of your Cumulocity cloud tenant. For more information, see TLS/SSL Secret. Info: The Edge operator retrieves this secret from the EDGE-CR-NAMESPACE. Ensure that this secret is created before initiating the Edge deployment or update process.

Field

Required

Type

Default

Description

domain Yes String Cumulocity cloud tenant domain. For example, <tenantid>.cumulocity.com

tlsSecretName

No

string

The Edge operator generates and assigns self-signed TLS/SSL private key and certificates.

Name of the Kubernetes secret containing the TLS/SSL private key and certificates with which Edge connects to the cloud through MQTT protocol using a X.509 certificate for authentication. This secret must contain two keys:

- tls.key: TLS/SSL private key in the PEM format.

- tls.crt: The TLS/SSL certificate chain associated with the private key in PEM format. It’s essential to ensure the certificates are arranged in the correct sequence for TLS/SSL validation to succeed. The proper order of the certificate chain is:

- End-entity certificate: This is the TLS/SSL certificate issued to your domain or server, sometimes referred to as the “leaf” or “server” certificate.

- Intermediate certificate(s): These certificates link your end-entity certificate to the trusted root certificate. If there are multiple intermediate certificates, they must be ordered correctly as well.

- Root CA certificate: This is the certificate for the Certificate Authority (CA) that is trusted by browsers and other clients. It’s generally included last in the chain.

Info: You can also reuse the secret name provided in the spec.tlsSecretName provided that the TLS/SSL certificate it references is issued by an intermediate Certificate Authority (CA) within your organization and can be added to the trusted certificate list of your Cumulocity cloud tenant.

For more information, see TLS/SSL Secret.

Info: The Edge operator retrieves this secret from the EDGE-CR-NAMESPACE. Ensure that this secret is created before initiating the Edge deployment or update process.

Cumulocity Core

The core specification specifies the fields for configuring the Cumulocity core node and its resource limits.

Field	Required	Type	Default	Description
resources.limits	Yes	Structure	Defaults to CPU Limit: 3000m Memory Limit: 6GB	Specify resource limits for the Cumulocity Core container. For more information, see Resource limits specification.

MongoDB

This field is necessary for one or more of the following reasons:

To specify the MongoDB admin credentials.
To specify resource limits for the MongoDB server containers deployed by the Edge operator.

Field	Required	Type	Default	Description
credentialsSecretName	No	String	Defaults to `databaseAdmin` and a generated password as the database admin user and password.	Name of the Kubernetes Secret containing the database admin credentials with which the MongoDB server must be configured. For more information, see MongoDB Credentials Secret. Info: The Edge operator retrieves this secret from the `EDGE-CR-NAMESPACE`. Ensure that this secret is created before initiating the Edge deployment or update process.
resources.limits	No	Structure	Defaults to CPU Limit: 3000m Memory Limit: 6GB	Specify resource limits for the MongoDB server pod. For more information, see Resource limits specification.
resources.requests	No	Structure	Defaults to 75 GB	Specify the size of the Persistent Volume Claim (PVC) named `mongod-data-edge-db-rs0-0` made by MongoDB server for persisting application data. For more information, see MongoDB storage size.

Field

Required

Type

Default

Description

credentialsSecretName

No

String

Defaults to databaseAdmin and a generated password as the database admin user and password.

Name of the Kubernetes Secret containing the database admin credentials with which the MongoDB server must be configured. For more information, see MongoDB Credentials Secret.

Info: The Edge operator retrieves this secret from the EDGE-CR-NAMESPACE. Ensure that this secret is created before initiating the Edge deployment or update process.

resources.limits No Structure Defaults to CPU Limit: 3000m
Memory Limit: 6GB Specify resource limits for the MongoDB server pod. For more information, see Resource limits specification.

resources.requests No Structure Defaults to 75 GB Specify the size of the Persistent Volume Claim (PVC) named mongod-data-edge-db-rs0-0 made by MongoDB server for persisting application data. For more information, see MongoDB storage size.

Resource limits specification

Structure for specifying the resource limits for the containers deployed by the Edge operator.

Field	Required	Type	Default	Description
cpu	No	String		Specific CPU limit in CPU units. For example, 1000m or 1M
memory	No	String		Specific memory limit in memory units. For example, 1000M or 1G

MongoDB credentials secret

Specifies the Kubernetes secret containing the admin credentials with which the MongoDB server must be configured. The Edge operator retrieves this secret from the namespace EDGE-CR-NAMESPACE. It is important that this secret is created before initiating the Edge deployment or update process.

This secret should contain the fields described in the table below:

Field	Required	Type	Default	Description
MONGODB_DATABASE_ADMIN_USER	Yes	String		Database admin username with which the MongoDB server is configured.
MONGODB_DATABASE_ADMIN_PASSWORD	Yes	String		Database admin password with which the MongoDB server is configured.

MongoDB storage size

Field	Required	Type	Default	Description
storage	No	string	Default to 75 GB	Specify the PVC storage. Info: Once Edge is installed, you can only increase this value, but cannot reduce.

Field

Required

Type

Default

Description

storage

No

string

Default to 75 GB

Specify the PVC storage.

Info: Once Edge is installed, you can only increase this value, but cannot reduce.

Microservices

The microservice specification allows specifying resources to allocate to default microservices, including the Apama, Smart Rules, OPCUA Management Service, and microservice-based data broker microservices.

Field	Required	Type	Default	Description
name	Yes	String		The name of the Cumulocity microservice. The allowed values are `apama-ctrl`, `smartrule`, `opcua-mgmt-service`, and `databroker-agent-server`.
resources.limits	No	Structure	Defaults to CPU Limit: 1000m Memory Limit: 1 GB	Specify resource limits for the Cumulocity microservice container. For more information, see Resource limits specification.