diff --git a/docs_src/microservices/general/database/Ch-Postgres.md b/docs_src/microservices/general/database/Ch-Postgres.md new file mode 100644 index 0000000000..6aef1d8249 --- /dev/null +++ b/docs_src/microservices/general/database/Ch-Postgres.md @@ -0,0 +1,76 @@ +# PostgreSQL + +EdgeX Foundry also supports PostgreSQL as the persistence database. + +PostgreSQL is an open-source object-relational database system (licensed under the PostgreSQL License) that offers exceptional scalability and performance, with support for both relational and document (JSON) data models. + +## Pre-Defined Users with Privileges + +Each EdgeX service that connects to PostgreSQL uses different users depending on whether it's operating in secure or non-secure mode. + +In non-secure mode, all services use the default `postgres` user to access the PostgreSQL database. + +In secure mode, each EdgeX service is assigned a unique username and password, with limited privileges. These users are restricted to accessing only the table schemas owned by their respective services. +For instance, the Core Data service owns the `core_data` schema and is permitted to use the `core_data` user to access the database. This `core_data` user is granted privileges specific to the tables within the `core_data` schema. + +## Using PostgreSQL Database + +PostgreSQL database can be started and used as the persistence store in the Docker-based EdgeX deployment. + +Please refer to [Use PostgreSQL as the persistence layer in EdgeX](https://github.com/edgexfoundry/edgex-compose?tab=readme-ov-file#use-postgresql-as-the-persistence-layer-in-edgex) for the instructions to run the EdgeX services along with PostgreSQL database. + +## (Optional) Configure add-on services to access PostgreSQL + +This section introduces how to configure add-on services to access PostgreSQL database in secure mode. + +For more information about add-on services, see [Configuring Add-on Service](../../../security/Ch-Configuring-Add-On-Services/). + +### Configure known secrets for add-on services + +The `EDGEX_ADD_KNOWN_SECRETS` environment variable on `secretstore-setup` allows for known secrets +to be added to an add-on service's `Secret Store`. + +The `known` secret for PostgreSQL is the `PostgreSQL credentials` identified by +the name `postgres`. Any add-on service needing access to the `PostgreSQL` such as +App Service HTTP Export with Store and Forward enabled will need the `PostgreSQL credentials` +put in its `Secret Store`. + +Note that the steps needed for connecting add-on services to the `Secure MessageBus` are: + +1. Utilizing the `security-bootstrapper` to ensure proper startup sequence +2. Creating the `Secret Store` for the add-on service +3. Adding the `postgres` known secret to the add-on service's `Secret Store` + +and if the add-on service is not connecting to the PostgreSQL database, then this step can be skipped. + +So given an example for service `myservice` to use the PostgreSQL database in secure mode, +we need to tell `secretstore-setup` to add the `postgres` known secret to `Secret Store` for `myservice`. +This can be done through the configuration of adding `postgres[myservice]` into the environment variable +`EDGEX_ADD_KNOWN_SECRETS` in `secretstore-setup` service's environment section, in which `postgres` is the name of +the `known secret` and `myservice` is the service key of the add-on service. + +```yaml +... + secretstore-setup: + container_name: edgex-secretstore-setup + depends_on: + - security-bootstrapper + - vault + environment: + EDGEX_ADD_SECRETSTORE_TOKENS: myservice + EDGEX_ADD_KNOWN_SECRETS: postgres[myservice],message-bus[myservice],message-bus[device-virtual] +... + +``` + +In the above `docker-compose` section of `secretstore-setup`, we specify the known secret of +`postgres` to add/copy the PostgreSQL database credentials to the `Secret Store` for the `myservice` service. + +We can also use the alternative or simpler form of `EDGEX_ADD_KNOWN_SECRETS` environment variable's value like + +```yaml + EDGEX_ADD_KNOWN_SECRETS: postgres[myservice],message-bus[myservice],message-bus[device-virtual] +``` + +in which all add-on services are put together in a comma separated list associated with the +known secret `postgres`. diff --git a/docs_src/microservices/core/database/Ch-Redis.md b/docs_src/microservices/general/database/Ch-Redis.md similarity index 99% rename from docs_src/microservices/core/database/Ch-Redis.md rename to docs_src/microservices/general/database/Ch-Redis.md index 433ee53a75..8b077439d9 100644 --- a/docs_src/microservices/core/database/Ch-Redis.md +++ b/docs_src/microservices/general/database/Ch-Redis.md @@ -1,4 +1,4 @@ -# Redis Database +# Redis EdgeX Foundry's reference implementation database (for sensor data, metadata and all things that need to be persisted in a database) is Redis. diff --git a/docs_src/microservices/support/cronScheduler/GettingStarted.md b/docs_src/microservices/support/cronScheduler/GettingStarted.md index 096196fe8e..852b953ed6 100644 --- a/docs_src/microservices/support/cronScheduler/GettingStarted.md +++ b/docs_src/microservices/support/cronScheduler/GettingStarted.md @@ -97,31 +97,8 @@ A schedule action record records the information of a [ScheduleAction](#schedule ## Running Services with Support Cron Scheduler -The simplest way to run all the required services with support cron scheduler is to use the [Predefined Compose File](https://github.com/edgexfoundry/edgex-compose/) from a terminal window. - -1. Clone [https://github.com/edgexfoundry/edgex-compose/](https://github.com/edgexfoundry/edgex-compose/) - -2. Run the services - ``` - docker compose -f docker-compose-postgres-no-secty.yml up -d - ``` - Or run the services on ARM64 system - ``` - docker compose -f docker-compose-postgres-no-secty-arm64.yml up -d - ``` -This runs, in non-secure mode, all the standard EdgeX services, including Support Cron Scheduler, along with the Device Virtual. - -To stop the services - -``` -docker compose -f docker-compose-postgres-no-secty.yml down -``` - -Or stop the services on ARM64 system - -``` -docker compose -f docker-compose-postgres-no-secty-arm64.yml down -``` +Please refer to [Using PostgreSQL Database](../../general/database/Ch-Postgres/#using-postgresql-database) for instructions on how to get EdgeX services up and running with PostgreSQL database. +Following the steps in this guide, the Support Cron Scheduler service will be included among the services that are started. diff --git a/mkdocs.yml b/mkdocs.yml index edee822f24..e155272236 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -105,7 +105,6 @@ nav: - Source Code: microservices/core/command/SourceCode.md - Additional Details: - Regex Get Command: microservices/core/command/details/RegexGetCommand.md - - microservices/core/database/Ch-Redis.md - Supporting: - microservices/support/Ch-SupportingServices.md - Notifications: @@ -328,6 +327,9 @@ nav: - V3 Migration: microservices/configuration/V3MigrationCommonConfig.md - microservices/general/index.md - microservices/general/messagebus.md + - Database: + - microservices/general/database/Ch-Redis.md + - microservices/general/database/Ch-Postgres.md - Security: - Security Services: security/Ch-Security.md - security/Ch-SecretStore.md