aerOS installation

Introduction 

The formal description of the aerOS installation procedure (without technical aspects) is available in the section “3.2 aerOS installation” of “D5.2 Integration, evaluation plan and KPIs definition”. This content is currently being updated and improved in the next version of this deliverable, D5.7, which will be delivered the next month.

The installation process of aerOS Meta-OS components to finally achieve a complete and functional IoT-Edge-Cloud continuum starts with a set of ready and operational computing resources upon which it is intended to be built. These computing resources must accomplish a set of requirements defined in section 5.4.1 of the D2.7 (capacity of running containerised workloads or availability of computing and networking capabilities, among others) to become Infrastructure Elements, the most granular entity able to be controlled and managed by the Meta-OS. Thus, it is important to highlight that the starting point of this setup process is not the low-level preparation of these computing resources (installing an OS or containerization tools such as K8s clusters or Docker, for instance), but rather creating the first domain of the continuum: the entrypoint domain.

Please, bear in mind that aerOS domains can be of K8s nature or just Docker environments. This is because the only mandate is for them to be able to run containerised workloads. Thus, select the option that suits your particular case better.

Prerequirements 

Kubernetes 

Create the common-deployments secret to be able to pull all the aerOS container images:

kubectl create secret docker-registry aeros-common-deployments --docker-server=registry.gitlab.aeros-project.eu --docker-username=<username> --docker-password=<token>

Add common-deployments (named as aeros-common) Helm chart repository:

helm repo add --username <username> --password <token> aeros-common https://gitlab.aeros-project.eu/api/v4/projects/65/packages/helm/stable

Docker 

Docker login to aerOS Gitlab registry to be able to pull all the aerOS container images:

docker login registry.gitlab.aeros-project.eu -u <username> -p <token>

Network 

According to the final version of the aerOS architecture (D2.7), each domain must have a public URL that must be reachable by the other domains that make up the continuum. Therefore, the infrastructure must be compliant with these requirements before proceeding with the installation. Similarly, some aerOS service must be exposed through this domain public URL through HTTPS, such as the API Gateway, Keycloak or the Management Portal, so it is in charge of the system administrator or the installer to select the most appropriate way to achieve it depending on the underlying infrastructure. For instance, in K8s environments, the Helm charts of these components provide Ingress definitions, use of NodePorts or even direct TLS certificates configuration for HTTPS exposure. In some scenarios (such as in the aerOS MVP), the deployment of an Ingress is enough to expose those services, but in more restrictive scenarios, an external proxy must be configured to allow the redirection to the proper Ingress or the NodePorts.

Related with this explanation, the installation and configuration of load balancers (e.g. MetalLB) or Ingress Controllers (e.g. Nginx Ingress Controller) in K8s are not part of the aerOS Meta-OS nor aerOS services, so this installation guide doesn’t aim to cover them. However, some installation guidelines are provided in this documentation to help potential users to adopt the aerOS solution.

Useful information 

In this installation guide, the aerOS component’s installation commands are provided with only the key or required configuration values, along with some examples or placeholders in certain cases. Therefore, the link to each component’s documentation is attached in the title of each installation step, since a more detailed explanation of the configuration options is included in that specific documentation.

The aerOS team is aware that describing the specific configuration options of each component is always challenging, even more when describing the whole installation process of a Meta-OS with a complex architecture such as aerOS. Thus, the aerOS team commits to periodically update and enhance this guide, and also plan to deliver additional tools such as automated installation scripts to improve the installation of the aerOS Meta-OS and also the user experience, which can be helpful for externals users to the project who are not yet familiar with the aerOS terminology or architecture.

Finally, a FAQs section with some clarifications will be included in D5.7 to help users to adopt the aerOS solution.

Note

Please, take into consideration that the described components are under development, so this can lead into possible failures or inconsistences

Note

All the used container images and Helm charts are only available for the aerOS project partners and Open Call projects, but this content will be publicly delivered in the near future under an open-source license.

Note

All the content enclosed in <> are just placeholders, so please, replace them with the appropiate value

1. Entrypoint domain 

1. Install Federation enablers: Orion-LD Context Broker and aerOS Federator 

1.1 Install Orion-LD Context Broker.

Kubernetes

In K8s install the Helm chart setting the DomainID and subordinateEndpoint (only if it is expected to use distributed NGSI-LD subscriptions, otherwise it can be avoided) parameters:

helm install orion-ld aeros-common/orion-ld --set broker.args.brokerId=<DomainID> --set broker.service.ports.api.nodePort=31026 --set broker.args.traceLevel="70-99" --set subordinateEndpoint=<domain-public-url>/orionld/ex/v1

Note

You can directly reach (without passing through KrakenD) the Orion-LD API through http://k8s-node-ip:31026 for testing purposes

Docker

In Docker machines, get the docker-compose.yaml file and then edit it to set the DomainID parameter:

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/orion-ld/1.1.0/docker-compose.yaml

Note

You can directly reach (without passing through KrakenD) the Orion-LD API through http://machine-ip:1026 for testing purposes

1.2 Install aerOS Federator 

The aerOS Federator must be configured to act as the entrypoint domain federator (this mode includes features that are not present in the federators of the other domains), so the IS_ENTRYPOINT environment variable must be set to true. Furthermore, this component creates (if not present) the Domain entity in Orion-LD, so some environment variables starting with the DOMAIN_ prefix (DOMAIN_NAME, DOMAIN_DESCRIPTION, DOMAIN_OWNER and DOMAIN_PUBLIC_URL) must be properly configured to create this entity and achieve a functional domain. Finally, the peer federator (PEER_FEDERATOR_URL) isn’t needed in the entrypoint federator, so the PEER_FEDERATOR_URL doesn’t have to be filled or the default value can be used.

A more detailed explanation of the configuration options is provided in the aerOS Federator documentation.

Kubernetes

It is recommended to create a YAML file with the custom values. For example:

federator:
    envVars:
        isEntrypoint: true
        domain:
            name: Domain01
            description: This is a new domain
            publicUrl: https://upv-domain.aeros-project.eu
            owner: UPV # This value will be used to create the Organization entity in Orion-LD
            cbUrl: http://orion-ld-broker.default.svc.cluster.local:1026

Then, install the Helm chart using the custom values from the previously created YAML file:

helm install federator aeros-common/federator -f custom-values.yaml

Docker

In Docker machines, get the docker-compose.yaml file and then edit it to set the proper values for the environment variables such as in the Helm chart:

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/federator/1.1.0/docker-compose.yaml

2. Install the Identity Manager: Keycloak and OpenLDAP

2.1 Install OpenLDAP

Currently, the installation of OpenLDAP is only available for K8s as a Helm chart. This chart is an enhancement of the official OpenLDAP chart which creates the defined aerOS roles and some predefined users assigned with these roles in the deployed OpenLDAP instance.

To install the Helm chart:

helm install openldap aeros-common/openldap-stack-ha --set ltb-passwd.ingress.enabled=false --set phpldapadmin.ingress.enabled=false --set phpldapadmin.service.type=NodePort --set persistence.size=100Mi --set replication.enabled=false --set replicaCount=1 --debug

This is the list of defined roles in aerOS according to D3.1 and D3.2:
- aerOS User
- Vertical deployer
- Data Product owner
- Continuum Administrator
Optionally, you can access to its phpldapadmin dashboard to inspect the available users and roles. For this, you have to first port-forward the openldap-phpldapadmin service:

kubectl port-forward service/openldap-phpldapadmin 81:80

and then access to it via http://localhost:81

2.2 Install Keycloak

Warning

If Keycloak will be exposed behind a reverse proxy (e.g. through a K8s Ingress), you must set the PROXY_ADDRESS_FORWARDING env var to true

Warning

Take into consideration that Keycloak must be reachable by the user’s browser when accessing to the Management Portal. Therefore, it can be exposed through a K8s ingress, through a NodePort or exposing the Docker container port to the host machine. It will depend on the specific needs or network configuration of the use case.

This component supports the configuration of TLS certificates to be reachable through HTTPS without the need of additional components. Check the Helm chart values or the Docker compose file.

Kubernetes

Expose via NodePort:

helm install idm aeros-common/idm --set keycloak.service.ports.keycloak.nodePort=<nodePort> --debug

Expose via Ingress (default ingress configuration, please check the values):

helm install idm aeros-common/idm --set keycloak.envVars.proxyAddressForwarding=true --set keycloak.ingress.enabled=true --debug

Docker

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/idm/1.1.0/docker-compose.yaml

docker compose up -d

2.3 Keycloak configuration

Steps 1-3 are described with more details in the guide provided by S21SEC, which can be downloaded by running the below command. Please, download it again if you have downloaded a previous version.

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/aerOS_Keycloak_OpenLDAP_for_UCs/1.2.0/aerOS_Keycloak_OpenLDAP_for_UCs.pptx

Access to Keycloak URL with the admin credentials (by default admin/Pa55w0rd). Please, modify the default credentials using the chart values
Create a new Realm: open the realms list on the top left and click on Create Realm
Go to User federation -> Add Ldap providers -> Fill in the form with the proper OpenLDAP configuration.
Create a new Client for the Management Portal.
- Go to Clients -> Click on Create client -> Fill in the Client ID and Name fields with the selected value (e.g. managementportal) -> Click on Next -> Click on Save

Note

This Client configuration will be used for the Management Portal installation (step #6).

The most important configurable parameters are the ones related with the redirect URIs, which must point to the portal’s access URL (e.g., a public domain such as “https://management-portal.aeros-project.eu/” or an internal IP such as “http://192.168.1.177:31580/”)

Create new clients and roles for internal components authentication.
These clients will be used to obtain valid tokens in trusted aerOS applications such as HLO components, LLO and aerOS Federator

5.1 Create two Clients: HLO and ContextBroker
Go to Clients -> Click on Create client -> Fill in the Client ID and Name fields with the proper value -> Click on Next

Enable Client authentication and then select Service accounts roles -> Click on Save
5.2 Create two Realm Roles: HLO and ContextBroker
- Go to Realm roles -> Click on Create role -> Fill in the Role name field -> Click on Save
5.3 Assign the each role to the corresponding client (e.g. HLO role to HLO client)
- Go to Clients -> Click on the proper client -> Click on the Service accounts roles tab -> Click on Assign role -> Select the proper role -> Click on Assign

2.4. Installation of aeros-k8s-shim

aerOS-K8s-shim provides a bridge between aerOS and Kubernetes. It produces critical aerOS secrets and ConfigMaps, storing them in the underlying K8s environment. These objects include a private/public key pair for each domain, JWT tokens to authorize machine-to-machine (m2m) communication among HLO components and Context Broker, and WireGuard configuration for network overlay establishment.

This component exposes an expandable API which receives requests for accomplishing K8s-related tasks. K8s secrets, ConfigMaps, pods, and other objects are abstracted. For this reason, a service account, a role, and an appropriate role binding ensure controlled access to K8s APIs.

Currently, the APIs offer:

M2M tokens, acquired from the entrypoint domain Keycloak
WireGuard network component re-configuration for network overlays implementation
Creation of private and public keys for the aerOS domain

The private and public keys are pushed into a K8s secret. The public key is also pushed into the aerOS continuum domain entity in the “publicKey” attribute. On initialization, it sets the K8s context and creates domain keys; then, the API takes over.

To install the aeros-k8s-shim component, follow these steps:

Retrieve the default values file:

helm show values aeros-common/aeros-k8s-shim > aeros-k8s-shim-values.yaml

Edit the necessary values in the aeros-k8s-shim-values.yaml file, such as:

keycloak_url: "https://keycloak.cf-mvp-domain.aeros-project.eu"  # URL of the Keycloak server
realm_openldap: "keycloack-openldap"   # Keycloak realm that has been created in the previous step
client_secret_cb: "<ContextBroker_Secret>" # Client Secret for the Context Broker that has been created in the previous step
client_secret_hlo: "<HLO_Secret>"      # Client secret for the HLO that has been created in the previous step

The rest can be left as default.

Install the chart:

helm install aeros-k8s-shim aeros-common/aeros-k8s-shim -f aeros-k8s-shim-values.yaml --debug

Useful API endpoints if needed:

To use the API endpoints, first exec into the pod:

kubectl exec -it <pod-name> -- bash
apt update && apt install curl

To retrieve the Context Broker token:
```
curl localhost:8000/token/cb
```
To retrieve the HLO token:
```
curl localhost:8000/token/hlo
```

3. Create Organization entity 

Note

If you have installed the aerOS Federator from version 1.1.0 (check the container image tag) onwards, the Domain entity should have been automatically created in Orion-LD, so you can skip this step.

Create an Organization and entity in Orion-LD:

curl --location 'http://<Orion_URL>/ngsi-ld/v1/entities' \
--header 'aerOS: true' \
--header 'Content-Type: application/json' \
--data '{
    "id": "urn:ngsi-ld:Organization:<Your_Organization_Name>",
    "type": "Organization",
    "name": {
        "type": "Property",
        "value": "<Your_Organization_Name>"
    }
}'

4. Install the KrakenD API Gateway with the proper configuration

Warning

The Public URL of the Domain, which has been configured in the aerOS Federator, must point to the KrakenD API Gateway. Therefore, it can be exposed through a K8s ingress, through a NodePort or exposing the Docker container port to the host machine. It will depend on the specific needs or network configuration of the use case.

This component supports the configuration of TLS certificates to be reachable through HTTPS without the need of additional components. Check the Helm chart values or the Docker compose file.

Kubernetes

First, check the configuration of the krakend.config object in the Helm chart values, where the endpoints of the aerOS components such as Orion-LD or HLO-FE are configured to be reachable by KrakenD. These endpoints must point to the URLs of the deployed components in the domain.

Some additional guidelines will be provided to add additional endpoints to the KrakenD configuration using the additionalEndpoints array (e.g. a pilot wants to expose an internal/custom non-aerOS API via KrakenD).

krakend:
    additionalEndpoints: []
    config:
        benchmarkPort: 3000
        disableHealthEndpoint: false
        federatorUrl: http://federator.default.svc.cluster.local:8050
        hloAllocatorUrl: http://hlo-allocator-service.default.svc.cluster.local:8082
        hloFeUrl: http://hlo-fe-service.default.svc.cluster.local:8081
        keycloakUrl: https://keycloak.cf-mvp-domain.aeros-project.eu
        keycloakRealm: keycloak-openldap
        logLevel: DEBUG
        orionCacheDuration: 3600
        orionUrl: http://orion-ld-broker.default.svc.cluster.local:1026
        selfApiPort: 8600
        sharedCacheDuration: 900
        iotaAPIUrl: http://iota-api:6000
        dataProductManagerUrl: http://data-fabric-data-product-manager.default.svc.cluster.local:8000
        dataCatalogManagerUrl: http://data-fabric-data-catalog-service.default.svc.cluster.local:8080

To install the Helm chart only setting the Keycloak configuration values:

helm install api-gateway aeros-common/api-gateway --set krakend.config.keycloakUrl=<YOUR_KEYCLOAK_URL> --set krakend.config.keycloakRealm=<YOUR_KEYCLOAK_REALM> --debug

To install the Helm chart using a custom values file:

helm install api-gateway aeros-common/api-gateway -f krakend-values.yaml --debug

Docker

First download and configure the krakend.json file using the proper endpoints of the aerOS components:

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/api-gateway/1.6.0/krakend.json

Then, download the Docker compose file and edit it to include the krakend.json file as a volume

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/api-gateway/1.6.0/docker-compose.yaml

Finally, run the Docker Compose file:

docker compose up -d

5. Install Self-* modules in all the IEs of the domain

Warning

If you have used the images of the Self-awareness with the tag 1.1.0-legacy-entity-id, remove all the previously created entities of type InfrastructureElement and then reinstall Self-awareness.

Warning

Before installing the Self-* modules, check the Orion URL configuration in Docker compose file or in the chart’s values file.

Warning

It is recommended to not install the Self-awareness’ power consumption module in IEs with constrained hardware resources (e.g. Raspberry Pis).

Currently, this guide only covers the installation of Self-awareness and Self-orchestrator modules, but other Self-* modules will be added soon.

Kubernetes

Check the values files and install the charts:

helm install self-awareness aeros-common/self-awareness --debug

helm install self-orchestrator aeros-common/self-orchestrator --debug

Docker

First, download the Docker compose files

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/self-awareness/1.4.3/self-awareness_docker-compose.yml

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/self-orchestrator/1.2.0/self-orchestrator_docker-compose.yml

Then, edit the Docker Compose files with the proper configuration parameters and install them:

docker compose up -d

6. Install the Management Portal 

Warning

Take into consideration that the Management Portal must be reachable through the user’s browser. Therefore, it can be exposed through a K8s ingress, through a NodePort or exposing the Docker container port to the host machine. It will depend on the specific needs or network configuration of the pilot/environment.

First, check the Keycloak’s Realm and Client that you created in step #2.4 for the management portal because they are needed for the installation. Keep in mind that the installation must be done to align the access URL of the portal with the redirect URIs that you configured in #2.4.4. However, if this URL changes or even you want to add more URLs, you can update the configuration of the Client in Keycloak and it will be transparent for the Management Portal because the Portal only needs to know the URL, the Realm and the Client that you’ve configured in Keycloak.

Detailed instructions will be provided as this is the most “manual” or different step for each continuum installation.

This component supports the configuration of TLS certificates to be reachable through HTTPS without the need of additional components. Check the Helm chart values or the Docker compose file.

Kubernetes

The installation is done using Helm chart, so first, check the frontend.keycloak and backend.envVars.keycloakUrl objects of the values file to edit it if needed:

Expose via NodePort:

helm install management-portal aeros-common/management-portal --set frontend.service.ports.web.nodePort=<nodePort> --debug

Expose via Ingress (default ingress configuration, please check the values):

helm install management-portal aeros-common/management-portal --set frontend.ingress.enabled=true --debug

Docker

Create a config folder, download the keycloak.json and managementportal.conf files inside it. Then edit both files.

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/management-portal/1.0.2/keycloak.json
wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/management-portal/1.0.2/managementportal.conf

Download the Docker compose file and edit it.

cd ..
wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/management-portal/1.0.2/docker-compose.yaml

Run the Docker compose file.

docker compose up -d

7. Install HLO and Redpanda 

7.1 Redpanda

Warning

DO NOT use a virtualized CPU (e.g. kvm64) because the Redpanda installation will fail.
For machines with SELinux enabled, it is needed a customization of the official Helm chart.

Install the official redpanda chart using these custom values, so save these values into a file named aeros-values.yaml:

statefulset:
    initContainers:
        setDataDirOwnership:
            enabled: true
    replicas: 1
tls:
    enabled: false
monitoring:
    enabled: false
    scrapeInterval: 30s
storage:
    persistentVolume:
        size: 500Mi

If Prometheus has been previously installed in the K8s cluster, you can enable the monitoring of Redpanda by setting monitoring -> enabled: true

helm repo add redpanda https://charts.redpanda.com
helm install redpanda redpanda/redpanda -n redpanda --create-namespace -f aeros-redpanda-values.yaml --debug

Using the customized redpanda chart you can avoid the topic creation (step 7.2) cause they are created automatically.

helm repo update
helm install redpanda -n redpanda aeros-common/redpanda --version 5.7.8

Note

It is recommended to review the values.yaml file before deploying the Helm chart. This allows you to customize configurations like the storage class, replicas of brokers, monitoring, etc.
helm show values aeros-common/redpanda --version 5.7.8 > values.yaml

Once you’ve customized your values.yaml, deploy the chart with:

helm install redpanda aeros-common/redpanda --version 5.7.8 -f ./values.yaml

Check the official documentation

7.2 Topics creation in Redpanda

List of used topics by the HLO:

allocator2deployment
data2allocator
fe2data

There are two options to create the needed topics for the HLO in Redpanda:

port-forward the port 8080 of the redpanda-console pod or service, and then access to it via http://localhost:forwarded-port (in this command the forwarded-port is 8081). Finally, go to Topics -> Create topic.
kubectl port-forward service/redpanda-console 8081:8080

Create them using these commands. You can access to the console to check if they have been created:

K8s:

kubectl exec -it redpanda-0 -n redpanda -- rpk topic create allocator2deployment
kubectl exec -it redpanda-0 -n redpanda -- rpk topic create data2allocator
kubectl exec -it redpanda-0 -n redpanda -- rpk topic create fe2data

Docker:

docker exec -it redpanda-0 rpk topic create allocator2deployment
docker exec -it redpanda-0 rpk topic create data2allocator
docker exec -it redpanda-0 rpk topic create fe2data

7.3 HLO 

Currently, all components can be installed using an umbrella Helm chart which installs all the Helm charts of the HLO components in the same K8s cluster. It’s available in the Helm chart repository of the common-deployments Gitlab repository.

All the components of the HLO are:

HLO Front End, which exposes the API endpoints to receive descriptors expressing IoT service deployment requests and related resource constraints.
HLO Data Aggregator, which queries the continuum for candidate resources for every service component as part of the IoT service deployment.
HLO Allocator, which employs AI inference methods to predict and provide the most efficient IE out of the provided candidate list.
HLO Deployment Engine, which on one hand identifies the location of each IE for every service component and submits the deployment request for the chosen IE and on the other hand addresses LLO connected with the selected IE with the appropriate deployment template which integrates all information needed to proceed with the deployment of the service component on the chosen IE.

To proceed with deployment in an aerOS domain:

Ensure the proper context is used:

kubectl config use-context "your-aeros-domain-context"

Get default values (from chart) and store them locally:

helm show values aeros-common/hlo-deployments --version 1.0.0 > values.yaml

Update values for your environment:
```
vim values.yaml
```
Please note that most probably you do not need to change anything and this will work out of the box. But in case you have changed Orion-LD service name (during deployment) or port or have created in Redpanda topics with other names than the default ones (check 7.2 above), then you have to specify them here.

Install HLO using the updated file with your environment variables:

helm install hlo-components aeros-common/hlo-deployments --version 1.0.0 -f ./values.yaml

In the future, more detailed instructions will be provided to install each HLO component separately, and for the HLO installation in Docker machines.

8. Install LLO(s)

In aerOS, the LLOs are based on the K8s Operator Pattern, which provide a framework to automatically control the lifecycle management of resources. This does not mean that LLOs only support the management of K8s workloads, but that actually leverage this widely used and tested resource management framework to finally reflect the desired state of services (to be deployed in a certain IE), with a common way to express the Implementation Blueprints (custom K8s Custom Resources) that is independent on the container management framework used in the selected IE, thus agnostic for the HLO.

Warning

As aerOS LLOs are based on K8s Operators, the LLO API and the LLO Operators (LLO K8s, LLO Docker, …) must be installed in K8s clusters.

8.1 Prerequirements

Warning

Remember that each domain must contain at least one K8s cluster to be able to run the LLO Operators.
The LLO API and the LLO Operators must be installed in the same K8s cluster.
At least one LLO must be installed in each domain.

Install the LLO API in a K8s cluster:

helm install aeros-llo-api aeros-common/llo-api

8.2 Install LLO K8s 

It is recommended to create a YAML file with the custom values. For example:

controllermanager:
    envVars:
        appEnv: production
        aerosShimUrl: http://aeros-k8s-shim-service.default.svc.cluster.local:8085
        contextBroker:
            url: http://orion-ld-broker.default.svc.cluster.local:1026
            healthcheckMode: endpoint
            authMode: shim
        iota: true
        iotaApiUrl: http://iota-api.default.svc.cluster.local:6000
        managementPortal:
            notifications: true
            notificationsUrl: https://portal-mvp.aeros-project.eu/portal-backend/notifications
            authMode: shim

The default values file can be retrieved using the following command:

helm show values aeros-common/llo-k8s > llo-k8s-values.yaml

Then, install the LLO K8s Operator in the K8s cluster:

helm install llo-k8s aeros-common/llo-k8s -f llo-k8s-values.yaml

8.3 Install LLO Docker 

Note

A new version of the LLO Docker is under development, with a renewed architecture based on NATS broker pub/sub. When ready, the installation guide will be updated accordingly.

Install the NATS broker. It must be exposed (e.g. through NodePort, its default configuration) to be reachable by all the Docker IEs of the domain.

helm install llo-nats aeros-common/llo-nats

Install the LLO Docker Operator in the K8s cluster. It is recommended to create a YAML file with the custom values. For example:

controllermanager:
    envVars:
        appEnv: production
        aerosShimUrl: http://aeros-k8s-shim-service.default.svc.cluster.local:8085
        contextBroker:
            url: http://orion-ld-broker.default.svc.cluster.local:1026
            healthcheckMode: endpoint
            authMode: shim
        iota: true
        iotaApiUrl: http://iota-api.default.svc.cluster.local:6000
        managementPortal:
            notifications: true
            notificationsUrl: https://portal-mvp.aeros-project.eu/portal-backend/notifications
            authMode: shim
        natsUrl: nats://llo-nats-broker.default.svc.cluster.local:4222 # URL of the NATS broker

The default values file can be retrieved using the following command:

helm show values aeros-common/llo-docker-operator > llo-docker-operator-values.yaml

Then, install the LLO Docker Operator in the K8s cluster:

helm install llo-k8s aeros-common/llo-docker-operator -f llo-docker-operator-values.yaml

Deploy the Docker controller in each Docker IE of the Domain

First, download the Docker Compose file:

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/llo-docker/1.0.0/controller-docker-compose.yaml

Then configure the environment variables:

environment:
  - APP_ENV=production
  - NATS_URL=nats://192.168.250.124:30222 # Exposed URL of the NATS broker
  - LLO_ID=Domain01-Docker # ID of the LLO of type Docker: <DomainID>-Docker
  - IE_ID=bc2411ff154d # Final part (MAC address) of the ID of the IE

To obtain the LLO_ID and IE_ID, you can retrieve the entities of the Docker IEs from Orion:

curl --location 'http://<Domain_Orion_URL>/ngsi-ld/v1/entities?local=true&format=simplified&type=InfrastructureElement&attrs=hostname,domain,containerTechnology,lowLevelOrchestrator&q=containerTechnology=="Docker"'

Then, find in the response the NGSI-LD entity related with the IE in which is being installed the Docker controller. As an example, it could be:

{
    "id": "urn:ngsi-ld:InfrastructureElement:Mixed:bc24115781cd",
    "type": "InfrastructureElement",
    "domain": "urn:ngsi-ld:Domain:Mixed",
    "hostname": "aeros-continuum-docker-2",
    "containerTechnology": "Docker",
    "lowLevelOrchestrator": "urn:ngsi-ld:LowLevelOrchestrator:Mixed:Docker"
}

So the configuration values would be:

LLO_ID: Mixed-Docker

IE_ID: bc24115781cd

Finally, run the Docker Compose file:

DOCKER_GID=$(getent group docker | cut -d: -f3) docker compose up -d

9. Install IOTA 

In aerOS, IOTA is used as a tool to share relevant domain information between not only different IEs but also domains. IOTA provides a shared network between all nodes called the Tangle, which allows for secure and trustworthy feeless data transactions between different nodes. The data shared here is only meant to be the most important of data regarding the state of the network.

9.1 Kubernetes

First, you must know the name of the Kubernetes node you’re going to use as the main node in the domain - the node that will have the coordinator and the dashboards installed and linked to its hornet node. If you do not know this run the command

kubectl get nodes -o wide

You can install IOTA in the main domain using the command:

helm install iota aeros-common/iota --set isMainDomain=true --set mainIE=<main_IE_Node>

Once the components are installed you can access the dashboard on port 31011 of the node you set as the main node. You may have to forward the port from the cluster to access it.

When you have access to the dashboard, you will need to link the multiple nodes of the domain with the main node and for that you will have to manually retrieve the PeerID of the other hornet nodes in your domain. In order to do this you can do the following:

Launch the command kubectl get pods -o wide to retrieve the secondary hornet nodes, they should look something like “iota-hornet-tdp5z”.

Launch the command kubectl logs iota-hornet-zx4v5 | grep ", ID:" `` to retrieve the PeerID, it will look something like ``12D3KooWPgV3cEQYdurRaubrhnSWTsu6aiwFx5cDE7ru5r6ssXTx

Warning

Save the PeerID, you may not be able to retrieve it later, the pod logs get scribbed after a few days.

Login to the dashboard, default credentials are admin/admin, navigate to the ‘Peers’ tab to the left and click on “Add Peer”

Introduce the IP and port of the peer, it will look something like “/ip4/PEER_IP/tcp/15600” (15600 is the default peering port for all nodes)

Introduce the PeerID that you retrieved earlier.

Introduce the Alias you want for the peer.

Repeat these steps for all other secondary peers

Furthermore, you can retrieve the default values for IOTA with the following command:

helm get values iota

Once you have the values file you can edit said values manually or review the possible fields you can edit. Of particular value are:

network.envVars.COO_PRV_KEYS - The coordinator private key, must match the one found in the coordinator field of the file.

coordinator.envVars.COO_PRV_KEYS - The coordinator private key, must match the one found in the network field of the file.

hornet.services.clusterIP.ports - All the ports used by every hornet node, you can change them here if you wish.

dashboard.services.nodePort.ports - All the ports used by the dashboard, you can change them here if you wish.

9.2 Docker Installation

Additionaly, IOTA can also be installed using Docker.

Clone the repo from the GitLab ‘https://gitlab.aeros-project.eu/wp4/t4.5/iota’.
Go to the ‘./docker/main_domain’ folder and run sudo ./bootstrap.sh
Run docker-compose on the main file: sudo docker-compose -f hornet-main.yaml start

This will create the necessary initial structure and deploy a coordinator and dashboard linked to a hornet node.

The rest works similarly to the Helm installation, the connection between nodes and the ports for example.

Warning

You only need to run the bootstrap once, if you run it again you will delete the database and the current status of the coordinator.

9.3 Uploading data to IOTA

With the components deployed, the installation comes with an easy to use API to upload data to the Tangle. You can do it from inside the cluster with the following POST petition:

curl -i -k --location 'http://<iota-ie-ip>:30634/upload?node=iota-hornet' \
--header 'Content-Type: application/json' \
--data '{
    "tag": "self.reorquestration",
    "message": {
        "THIS CAN BE": "WHATEVER YOU WANT",
        "AS LONG AS THE": "DATA IS A JSON"
    }
}'

Please note that the only requirement is that the data is a JSON object with the two elements: tag and message. The contents of those elements can be whatever you want.

This petition if succesful will return you the BlockID of the uploaded message. You can use this to retrieve the message fromt the dashboard itself.

Additionally, an endpoint has been opened in KrakenD to upload from outside the cluster, you can do it with the following POST:

curl -i -k --location 'http://<domain-public-url>:30634/upload?node=iota-hornet' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <auth-token-from-keyloak>' \
--data '{
    "tag": "self.reorquestration",
    "message": {
        "THIS CAN BE": "WHATEVER YOU WANT",
        "AS LONG AS THE": "DATA IS A JSON"
    }
}'

2. Other domains 

1. Install Orion-LD Context Broker 

First, install Orion-LD as in step #1.1 from Entrypoint domain.

If you are going to install the aerOS Federator from version 1.1.0 (check the container image tag) onwards, the Domain entity will be automatically created in Orion-LD. Otherwise, create the needed Organization (only if the domain belongs to a new organization) entity as in step #3 from Entrypoint domain.

2. Install aeros-k8s-shim 

Same steps as above. The configuration related with Keycloak must be the same as there’s a single instance of Keycloak in the continuum.

3. Install KrakenD 

Same steps as above. Take into account that it must point to the only instance of Keycloak of the aerOS continuum, which is deployed in the entrypoint domain.

After the proper KrakenD installation and configuration, the public URL of the Domain must be known as it points to this KrakenD API Gateway. Remember that must be reachable by all the other domains.

4. Install aerOS Federator 

Install aerOS Federator as in step #1.2 from Entrypoint domain. However, for non-entrypoint domains, IS_ENTRYPOINT environment variable must be set to false, and a valid peer federator must be configured to enable the spreading process of the new Domain through the continum. If only the entrypoint domain exists, the peer federator must be the Federator of this entrypoint domain, but if the continuum is composed of more domain, any domain can be configured to act as the peer federator. Therefore, configure the PEER_FEDERATOR_URL environment variable to point to the selected Federator. In addition, remember that this component creates (if not present) the Domain entity in Orion-LD, so some environment variables starting with the DOMAIN_ prefix (DOMAIN_NAME, DOMAIN_DESCRIPTION, DOMAIN_OWNER and DOMAIN_PUBLIC_URL) must be properly configured to create this entity and finally achieve a functional domain.

For instance, in case of installing the Federator using the Helm chart, this could be a valid configuration:

federator:
    envVars:
        isEntrypoint: false
        domain:
            name: Domain02
            description: This is a new domain, which is not the entrypoint
            publicUrl: https://ncsrd-domain.aeros-project.eu # Must point to the previously installed KrakenD
            owner: NCSRD # This value will be used to create the Organization entity in Orion-LD (if not present)
            cbUrl: http://orion-ld-broker.default.svc.cluster.local:1026
        peerFederatorUrl: https://upv-domain.aeros-project.eu/federator # Must point to the "/federator" endpoint of the KrakenD of another domain (for instance the entrypoint)

In the former version of this installation guide, the needed NGSI-LD Context Source Registrations (CSRs) were created manually in all the context brokers. However, currently they are automatically created by the aerOS Federator, so this component has absolutelly enhanced and facilitated the aerOS installation process. The existence of this CSRs in Orion-LD can be checked with the following GET request:

curl --location 'http://<Domain_Orion_internal_URL>/ngsi-ld/v1/csourceRegistrations?csf=aerosDomainFederation==true' \

Or with this request if the request is sent to the Domain’s KrakenD (after installing KrakenD):

curl --location 'https://cf-mvp-domain.aeros-project.eu/csourceRegistrations?csf=aerosDomainFederation==true' \
--header 'Authorization: Bearer <auth-token-from-keyloak>'

5. Install Self-* in IEs 

Same steps as above.

6. Install HLO & Redpanda 

Same steps as above.

7. Install LLO(s)

Same steps as above.

8. Install IOTA 

There is only one difference, since this is not the entrypoint domain a coordinator will not be needed, also you will have to manually add at least one peer from the entrypoint domain in order for the messages to travel properly.

8.1 K8s Installation

Install IOTA using the following command:

helm install iota aeros-common/iota --set isMainDomain=false --set mainIE=<main_IE_Node>

Where <main_IE_Node> is the node where you want the dashboard to be installed.

With this done, you can add a connection between the main node of this secondary domain and a node from the main domain from the web dashboard. After accessing the dashboard on port 31011 you must:

Login as admin from the left vertical tab, the default credentials are admin / admin. Please, modify the default credentials using the chart values

Go to the Peers tab. You’ll see the other peers from the secondary domain.

Click on Add Peer at the top right of the peers list.

Input the required 3 fields:

The adress, which should be: /ip4/Main_Domain_IP/tcp/30500

The PeerID of the node you’re connecting to. This can be seen from the Home tab on the Dashboard itself of the main node installed in the other domain ( also on port 31011 by default ), you may have to login to that Dashboard in order to see it. It will be something like: 12D3KooWMsTJuY3yU4NruYLs5AC7eBaThRLZ2Ta4LWMKc5wS6xp4.

The alias you wish to give to the node you’re connecting to.

8.2 Docker Installation

From the main IOTA repo ‘https://gitlab.aeros-project.eu/wp4/t4.5/iota’ simply navigate to ‘./docker/secondary’ and run the sudo docker-compose -f hornet-secondary.yaml start. This will deploy a hornet node and link it to a dashboard. Connection between nodes is handled in the same way as the Helm deployment.

3. Add a new IE in an existing domain 

Install Self-* modules in IE. Remember that Orion-LD must be reachable by the new IE.
Install additional LLOs if needed.

aerOS installation

1.1 Install Orion-LD Context Broker.

Kubernetes

Docker

1.2 Install aerOS Federator

Kubernetes

Docker

2. Install the Identity Manager: Keycloak and OpenLDAP

2.1 Install OpenLDAP

2.2 Install Keycloak

Kubernetes

Docker

2.3 Keycloak configuration

2.4. Installation of aeros-k8s-shim

4. Install the KrakenD API Gateway with the proper configuration

Kubernetes

Docker

5. Install Self-* modules in all the IEs of the domain

Kubernetes

Docker

Kubernetes

Docker

7.1 Redpanda

7.2 Topics creation in Redpanda

7.3 HLO

8.1 Prerequirements

8.2 Install LLO K8s

8.3 Install LLO Docker

9.1 Kubernetes

9.2 Docker Installation

9.3 Uploading data to IOTA

8.1 K8s Installation

8.2 Docker Installation

1.2 Install aerOS Federator 

7.3 HLO 

8.2 Install LLO K8s 

8.3 Install LLO Docker 