Edge Custom Resource

This section describes the structure and configuration options available in the Cumulocity IoT 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 IoT 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 deploy. For example, 1018.0.0 for 10.18 and 1018.0.1 for a fix-1 of 10.18.
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 the logistics team for your region: - North and South America: LogisSrvus@softwareagusa.com - All Other Regions: LogisticsServiceCenterGER@softwareag.com 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.
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) according to your company policies, and submit it to your internal or external Certificate Authority (CA). When creating the CSR, in addition to providing the Common Name (CN), Organization (O), and other required details, you must specify the Subject Alternative Name (SAN) to request a multi-domain certificate. Ensure that the SAN includes the domain names for the “edge” tenant and Management tenant. If you plan to install Cumulocity IoT DataHub, include its domain name as well. For instance, if your Edge domain is myown.iot.com, make sure myown.iot.com, management.myown.iot.com, and datahub.myown.iot.com are listed in the SAN field. - 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.
cloudTenant	No	Structure		Cumulocity IoT 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. - 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. Info: This value is used only during the Edge installation and can’t be changed for existing installations.
core	No	Structure		Cumulocity IoT platform configurations. For more information, see Cumulocity IoT Core configurations.
mongodb	Yes	Structure		Configurations needed to deploy the MongoDB server managed by the Edge operator or connect to an external one. For more information, see MongoDB.
microservices	No	Array of Structure	The Edge operator deploys all the default Cumulocity IoT microservices, which include the Apama, Smart Rules, OPCUA Management Server microservices.	Specify resources to allocate to each of the default Cumulocity IoT 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.

Cloud tenant

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

To enable this, first register Edge as a device in the Cumulocity IoT cloud tenant. You can register Edge by providing the Cumulocity IoT cloud tenant URI, and optionally, TLS/SSL key and certificate chain with which Edge connects to cloud through MQTT protocol using a X.509 certificate for authentication. If you do not provide the TLS/SSL key and the certificate chain, the Edge operator uses an internally generated TLS/SSL key and certificate for identifying Edge as a device in the cloud tenant. For completing the registration process, sign into your cloud tenant and follow the steps described in Managing trusted certificates to add the Certificate Authority (CA) certificate to the trusted certificate list of your tenant. For more information, see Device certificates.

In case you let the Edge use the internally generated TLS/SSL key and certificates, you can download the CA certificate by using the command below:

kubectl get edge c8yedge -n c8yedge --output jsonpath='{.status.helpCommands.fetchGeneratedCACrt}' | sh

Info

Substitute the Edge name and namespace name c8yedge in the command above with the specific Edge name and namespace name you have specified in your Edge CR.

Once registered, you can access your Edge remotely as a device, monitor its metrics, upgrade its version and collect diagnostic data remotely.

Field	Required	Type	Default	Description
domain	Yes	String		Cumulocity IoT 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 IoT 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 IoT 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 IoT 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 IoT Core

The core specification specifies the fields for configuring the Cumulocity IoT 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 IoT 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 configure an externally hosted MongoDB server.
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 `admin-pass` as the database admin user and password for the Edge operator managed MongoDB or fails with validation error for the externally hosted MongoDB server. Info: For the MongoDB managed by the Edge operator, it is recommended to provide the database admin credentials secret, rather than relying on the default credentials assigned by the Edge operator.	Name of the Kubernetes Secret containing the database admin credentials with which the Edge operator managed MongoDB must be configured or the database admin credentials of the externally hosted MongoDB server. 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.
connectionString	No	String	If not provided, the Edge operator installs a single node MongoDB server and configures it with the admin credentials provided in `spec.mongodb.credentialsSecretName`	Connection string of the externally hosted MongoDB server. URI format: `mongodb://host1[:port1][,...hostN[:portN]]` Info: If you do not provide this value, the Edge operator installs a single node MongoDB server. Once Edge is installed and configured to use the MongoDB managed by the Edge operator, you cannot provide the `connectionString` to use an externally hosted MongoDB.
tlsSecretName	No	String	Not required if the TLS/SSL key and certificates are issued by a trusted public CA.	Secret for supplying the Certificate Authority (CA) certificate that issued the TLS/SSL key and certificates used to configure the TLS for the externally hosted MongoDB server. This allows the Edge operator to establish trust with the server. For more information, see Externally hosted MongoDB 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.
resources.limits	Yes	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 managed by the Edge operator must be configured or the admin credentials of the externally hosted MongoDB server. 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 managed by the Edge operator or the username of the externally hosted MongoDB server is configured.
MONGODB_DATABASE_ADMIN_PASSWORD	Yes	String		Database admin password with which MongoDB managed by the Edge operator or the password for the externally hosted MongoDB server is configured.
MONGODB_USER_ADMIN_USER	No	String	userAdmin	Only used when MongoDB is deployed and managed by the Edge operator.
MONGODB_USER_ADMIN_PASSWORD	No	String	Password provided in the field `MONGODB_DATABASE_ADMIN_PASSWORD`	Only used when MongoDB is deployed and managed by the Edge operator.
MONGODB_CLUSTER_ADMIN_USER	No	String	clusterAdmin	Only used when MongoDB is deployed and managed by the Edge operator.
MONGODB_CLUSTER_ADMIN_PASSWORD	No	String	Password provided in the field `MONGODB_DATABASE_ADMIN_PASSWORD`	Only used when MongoDB is deployed and managed by the Edge operator.
MONGODB_CLUSTER_MONITOR_USER	No	String	clusterMonitor	Only used when MongoDB is deployed and managed by the Edge operator.
MONGODB_CLUSTER_MONITOR_PASSWORD	No	String	Password provided in the field `MONGODB_DATABASE_ADMIN_PASSWORD`	Only used when MongoDB is deployed and managed by the Edge operator.
MONGODB_BACKUP_USER	No	String	backup	Only used when MongoDB is deployed and managed by the Edge operator.
MONGODB_BACKUP_PASSWORD	No	String	Password provided in the field `MONGODB_DATABASE_ADMIN_PASSWORD`	Only used when MongoDB is deployed and managed by the Edge operator.

Externally hosted MongoDB TLS/SSL Secret

Field	Required	Type	Default	Description
ca.crt	No	String		Certificate Authority (CA) certificate in PEM format. Only required if the externally hosted MongoDB is TLS/SSL enabled with a self-signed certificate or a certificate not issued by a publicly trusted CA.

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 a default microservice, which includes the Apama, Smart Rules, OPCUA Management Server and Device Simulator microservices.

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