Deploy Lissi Agent using Kubernetes
1. Prerequisites
1.1 Access to the Docker Images and Helm Chart
To set up the Lissi Agent using Kubernetes you are required to have access to:
Reading access to the docker images (access token provided by our Lissi Team)
milissi.azurecr.io/lissi-keycloak-theme-lissi
milissi.azurecr.io/lissi-agent
milissi.azurecr.io/lissi-agent-ui
milissi.azurecr.io/lissi-tails-server
The Lissi Agent Helm chart
1.2 Kubernetes Secrets
Sensitive information such as passwords and keys need to be provided as Kubernetes secrets before installing the Lissi Agent Helm chart.
Secret Name | Keys | Values | Description |
---|---|---|---|
|
| A 32-character alpha/numeric string is recommended | Authorization API key to access AcaPy endpoints |
| A 32-character alpha/numeric string is recommended | AcaPy wallet encryption key | |
|
| Any random secure password If the database is externally provisioned the password must correlate with the database user we wish to connect to | AcaPy wallet database password |
|
| Any random secure password If the database is externally provisioned the password must correlate with the database user we wish to connect to | Keycloak database access password |
| Any random secure password | Password for the Keycloak admin user, used to access the Keycloak admin web UI exposed at | |
|
| The API key will be provided by the Lissi Agent Team alongside the configuration files | |
|
| Any random secure password If the database is externally provisioned the password must correlate with the database user we wish to connect to | MongoDB access password |
|
| Follow this tutorial to set your | This secret is used to authorize the user to pull images from the private ACR registry |
|
| A 32-character alpha/numeric string is recommended | Adds a security layer to communicate with the acapy webhook endpoint |
Bundle secrets in a single file
There are multiple ways to manage Kubernetes secrets. One option is to bundle all secrets in a single yaml file as depicted below. Secrets can be separated by three hyphens (---
) between them.
secrets.yaml:
apiVersion: v1
kind: Secret
metadata:
name: mediator
type: Opaque
data:
apiKey: afdas13fh3d813hdasf=
---
To apply all secretes to a Kubernetes instance, execute the following terminal command.
kubectl apply -f secrets.yaml
Create a regcred
Secret
In order to ensure that images hosted on milissi.azurecr.io
are resolved as expected, a secret holding the auth String for Azure’s container registry needs to be created. This can be done by creating a JSON file similar to the one depicted below. The auth String must contain a base64 encoded user name and corresponding token.
docker-auth.json:
{
"auths": {
"milissi.azurecr.io": {
"auth": "asdfasdf1235asdföpkjlöasjdfasdf="
}
}
}
After having created the JSON file, a secret can be created using the following terminal command.
kubectl create secret generic regcred \
--from-file=.dockerconfigjson=<path/to/.docker/docker-auth.json> \
--type=kubernetes.io/dockerconfigjson
1.3 Register a Domain Name
Register a domain name that links to the public IP address of your Kubernetes cluster. The UI and the controller will respectively be accessible from this domain at https://YOUR.DOMAIN/
and https://YOUR.DOMAIN/ctrl/
.
2. Install the Helm Chart
The installation of the Lissi Agent Helm chart follows two steps:
Customization of the
values.yaml
Installation of the Helm chart.
2.1 Customization of the values.yaml
The provided configuration files present two values.yaml
files that set the desired values for a specific Kubernetes deployment. values-template.yaml
if passed to the helm install
command overwrites the duplicated values present in values.yaml
.
The following table provides an overview of the available configuration options.
Lissi Agent
Keys | Description |
---|---|
| The domain name from where the Lissi Agent will be accessible Note that the subcharts share the same public domain. Therefore it is important to use the anchor e.g. |
| Endpoint used to establish connections to other agents. It is possible to use the same value as |
| Boolean that indicates whether a default tenant should be created by the Lissi Agent. |
| List of CORS allowed origins or Defaults to |
| By default, no error message is returned to the clients in the context of server errors. In case the server error messages should be shared with the clients set it to |
| Name of the persistent volume you wish to attach to the pod. Stores the Lissi Agent’s MongoDB documents |
| This field can be used to match an existing storage policy |
| Requested storage capacity for the mongo documents |
| Boolean that indicates whether the Persistent volume should be statically provisioned |
| In case of static Persistent Volume provisioning describe the existing static volume configuration |
| Boolean that indicates whether a MongoDB database pod should be created or the controller should connect to an existing MongoDB |
| Protocol used for connection to MongoDB. The protocol is used to build the MongoDB connection string Only overload this value if the database is provisioned externally. |
| Query string of the connection string to the MongoDB Only overload this value if the database is provisioned externally. |
| Address from where MongoDB can be reached Only overload this value if the database is provisioned externally. |
| Port of the MongoDB. Can be left empty in case the port should not be specified. Only overload this value if the database is provisioned externally. |
| Name of the user used to access to the database In case the database is externally provisioned the user already needs to exist and requires the right to create new databases. |
| List of the domain names you would like to create TLS/SSL certificates for. |
purgeRoutines.enabled | Indicates if purge routines are enabled. If not provided default values are applied |
purgeRoutines.dataLifespan | Indicates for how long user-sensitive information is stored before removal by purge routine. If not provided default values are applied |
purgeRoutines.periodicity | Indicates how often to run purge routines. If not provided default values are applied |
MongoDB Query String
The MongoDB Query String is generated based on the different values from the values.yaml as well as the password stored in the K8s secret.
<MONGODB_PROTOCOL>://<MONGODB_USERNAME>:<MONGODB_PASSWORD>@<MONGODB_HOST>:<MONGODB_PORT>/<SPRING_DATA_MONGODB_DATABASE>?<MONGODB_QUERY_STRING>
Tails-Server
Keys | Description |
---|---|
| The same public domain must be used to access the revocation registry. For that reason it is recommended to keep the |
| Name of the persistent volume you wish to attach to the pod. Stores the revocation registry |
| Requested storage capacity for the revocation registry |
| This field can be used to match an existing storage policy |
| Boolean that indicates whether the Persistent volume should be statically provisioned |
| In case of static Persistent Volume provisioning describe the existing static volume configuration |
|
Keycloak
Keys | Description |
---|---|
| The same public domain must be used to access Keycloak from the domain name for that reason it is recommended to keep the set anchor |
| Name of the persistent volume you wish to attach to the pod. Stores the realms, users as well as the client application |
| This field can be used to match an existing storage policy |
| Requested storage capacity for the Keycloak database |
| Boolean that indicates whether a new Postgres database pod should be created or the controller should connect to an existing Postgres database |
| Address of the Postgres database Only overload this value if the database is provisioned externally. |
| Port of the Postgres database |
| Name of the database that should be used Only overload this value if the database is provisioned externally. |
| Name of the user used to access to the database In case the database is externally provisioned the user already needs to exist and requires read and write rights for the database specified by |
| Boolean value that activate a custom keycloak configuration defined in the realm configMap (see Section 2.2.3 Custom Keycloak Config) |
| Boolean value that activate a custom keycloak configuration defined in the users configMap (see Section 2.2.3 Custom Keycloak Config) |
| Distributed cache is enabled by default. In case we provide “local“ parameter it is set to be disabled between nodes |
AcaPy
Keys | Description |
---|---|
| The same public domain must be used to access AcaPy from the domain name for that reason we recommend to keep the set anchor |
| The label is the SSI agents name that users see when connecting to your SSI agent. |
| The image URL is used by SSI wallets to show users a logo of your company when they are connecting to your SSI agent. |
| Name of the persistent volume you wish to attach to the pod. Stores the Acapy wallet encrypted information |
| This field can be used to match an existing storage policy |
| Requested storage capacity for the Acapy wallet |
| Boolean that indicates whether a Persistent volume should be statically provisioned |
| |
| Name of the ledger that acapy should connect to |
| Use this field to describe the ledger that acapy should connect to |
| Boolean that indicates whether a new Postgres database pod should be created or the controller should connect to an existing Postgres database |
| Address of the Postgres database Only overload this value if the database is provisioned externally. |
| Port of the Postgres database |
| Name of the user used to access to the database In case the database is externally provisioned the user already needs to exist and requires the right to create new databases. |
2.2.3 Custom Keycloak Configuration
It is possible to import a custom json formatted keycloak configuration leveraging the configMaps.
Custom Realm
Create a file
charts/keyckloak/templates/realm-config.yaml
apiVersion: v1 kind: ConfigMap metadata: name: realm-config data: lissi-cloud-realm.json: | { /** Your custom realm JSON description **/ }
CODEIn the parent Helm Chart set
keycloak.customKeycloak.realm = true
To update an existing deployment with latest changes
Adopt the migration strategy to
OVERWRITE_EXISTING
incharts/keycloak/templates/deployment.yaml
of the keycloak Chart.OR Run a manual migration directly from the Keycloak Container (cf: Keycloak Migration)
Custom Users
Create a file
charts/keyckloak/templates/users-config.yaml
apiVersion: v1 kind: ConfigMap metadata: name: users-config data: lissi-cloud-users-0.json: | { /** Your custom users JSON description **/ }
CODEIn the parent Helm Chart set
keycloak.customKeycloak.users = true
To update an existing deployment with latest changes
Adopt the migration strategy to
OVERWRITE_EXISTING
incharts/keycloak/templates/deployment.yaml
of the keycloak Chart.OR Run a manual migration directly from the Keycloak Container (cf: Keycloak Migration)
2.2 Installing the Helm Chart
Once the value-template.yaml
file configured as desired and connected to your cluster, through a terminal, navigate to the root of the configuration files and run the following command.
helm install [NAME] ./ -f ./values-template.yaml [ADDITIONAL_FLAGS]
More information on Helm chart installation and flags here: https://helm.sh/docs/helm/helm_install/
2.3 Test the Lissi Agent
After a couple of minutes, the agent is fully set up and accessible through the registered domain name https://{DOMAIN}/
. To login to the Lissi Agent use the username lissi
and password lissi
. On your first login, you are requested to change the password to a secure password of your choice.