diff --git a/assemblies/assembly-configuring-a-proxy.adoc b/assemblies/assembly-configuring-a-proxy.adoc index 5c2d5c8aad..ad74cd580d 100644 --- a/assemblies/assembly-configuring-a-proxy.adoc +++ b/assemblies/assembly-configuring-a-proxy.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: running-behind-a-proxy [id="{context}"] = Running {product} behind a corporate proxy @@ -21,3 +22,4 @@ include::modules/configuring-a-proxy/proc-configuring-proxy-in-operator-deployme include::modules/configuring-a-proxy/proc-configuring-proxy-in-helm-deployment.adoc[leveloffset=+1] +:context: {previouscontext} diff --git a/assemblies/assembly-configuring-external-postgresql-databases.adoc b/assemblies/assembly-configuring-external-postgresql-databases.adoc index 360e714886..cdff415477 100644 --- a/assemblies/assembly-configuring-external-postgresql-databases.adoc +++ b/assemblies/assembly-configuring-external-postgresql-databases.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: configuring-external-postgresql-databases [id="{context}"] = Configuring external PostgreSQL databases @@ -21,3 +22,4 @@ include::modules/configuring-external-databases/proc-configuring-postgresql-inst include::modules/configuring-external-databases/proc-migrating-databases-to-an-external-server.adoc[leveloffset=+1] +:context: {previouscontext} diff --git a/assemblies/assembly-configuring-high-availability.adoc b/assemblies/assembly-configuring-high-availability.adoc index 00b960ca7e..be8cd13aa7 100644 --- a/assemblies/assembly-configuring-high-availability.adoc +++ b/assemblies/assembly-configuring-high-availability.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: HighAvailability [id="{context}"] = Configuring high availability in {product} @@ -9,7 +10,7 @@ High availability (HA) is a system design approach that ensures a service remain {product} supports HA deployments on the following platforms: * {ocp-brand-name} -* {aks-name} +* {aks-name} * {eks-name} The HA deployments enable more resilient and reliable service availability across supported environments. @@ -25,4 +26,7 @@ As an administrator, you can configure high availability by adjusting replica va include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-operator-deployment.adoc[leveloffset=+1] -include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1] \ No newline at end of file +include::modules/configuring-high-availability/proc-configuring-high-availability-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1] + +:context: {previouscontext} +!:previouscontext: diff --git a/assemblies/assembly-configuring-readonlyrootfilesystem.adoc b/assemblies/assembly-configuring-readonlyrootfilesystem.adoc index e43b2ac7ce..81ba8b0ccf 100644 --- a/assemblies/assembly-configuring-readonlyrootfilesystem.adoc +++ b/assemblies/assembly-configuring-readonlyrootfilesystem.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: readonlyrootfilesystem [id="{context}"] = Configuring readOnlyRootFilesystem in {product} @@ -10,4 +11,6 @@ The {product} deployment consists of two containers: an `initContainer` that ins include::modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-operator-deployment.adoc[leveloffset=+1] -include::modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1] \ No newline at end of file +include::modules/configuring-readonlyrootfilesystem/proc-configuring-readonlyrootfilesystem-option-in-rhdh-helm-chart-deployment.adoc[leveloffset=+1] + +:context: {previouscontext} diff --git a/assemblies/assembly-provisioning-a-custom-configuration.adoc b/assemblies/assembly-provisioning-a-custom-configuration.adoc index 63e6c642d6..cf093c0d39 100644 --- a/assemblies/assembly-provisioning-a-custom-configuration.adoc +++ b/assemblies/assembly-provisioning-a-custom-configuration.adoc @@ -1,4 +1,5 @@ :_mod-docs-content-type: ASSEMBLY +:previouscontext: {context} :context: provisioning-and-using-your-custom-configuration [id="{context}"] = Provisioning and using your custom {product} configuration @@ -26,3 +27,4 @@ include::modules/configuring/proc-mounting-additional-files-in-your-custom-confi include::modules/configuring/proc-using-the-helm-chart-to-run-rhdh-with-your-custom-configuration.adoc[leveloffset=+1] +:context: {previouscontext} diff --git a/modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc b/modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc similarity index 98% rename from modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc rename to modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc index 65f32d7b58..ccb55936c3 100644 --- a/modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc +++ b/modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc @@ -1,4 +1,4 @@ -[id="proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_{context}"] +[id="configuring-an-rhdh-instance-with-tls-in-kubernetes"] = Configuring an {product-very-short} instance with a TLS connection in Kubernetes You can configure a {product-very-short} instance with a Transport Layer Security (TLS) connection in a Kubernetes cluster, such as an Azure Red Hat OpenShift (ARO) cluster, any cluster from a supported cloud provider, or your own cluster with proper configuration. Transport Layer Security (TLS) ensures a secure connection for the {product-very-short} instance with other entities, such as third-party applications, or external databases. However, you must use a public Certificate Authority (CA)-signed certificate to configure your Kubernetes cluster. diff --git a/modules/configuring/proc-preparing-your-external-services.adoc b/modules/configuring/proc-preparing-your-external-services.adoc new file mode 100644 index 0000000000..6a20f64b36 --- /dev/null +++ b/modules/configuring/proc-preparing-your-external-services.adoc @@ -0,0 +1,116 @@ +[id="preparing-your-external-services"] += Preparing your external services + +{product} relies on external services. +Prepare the required external services. + +PostgreSQL database:: +{product-short} stores data in a PostgreSQL database. +For resiliency, use an external database and include it in your disaster recovery plan. + +Redis cache:: +For efficiency, {product-short} caches plugin and Techdocs assets when your provide a Redis cache server. + +GitHub API access:: +Provide credentials to a GitHub app to enable access to the GitHub API for repository discovery. + +Connection to your identity provider:: +Provide credentials to your identity provider to enable user provisioning and authentication. + +.Procedure +* Get your external PostgreSQL database connection strings and certificates. +postgres-host::: Your PostgreSQL instance Domain Name System (DNS) or IP address. +postgres-port::: Your PostgreSQL instance port number, such as 5432. +postres-username::: The user name to connect to your PostgreSQL instance. +postgres-password::: The password to connect to your PostgreSQL instance. +postgres-ca.pem::: +postgres-key.key::: +postgres-crt.pem::: +For security, use TLS certificates to secure the connection to the database. + +. Get your Redis cache server connection string, such as `rediss://user:pass@cache.example.com:6379`. +For security, consider using a `rediss` secure server connection. + +. To allow {product-short} to access the GitHub API for repository, create a GitHub App. +Opt for a GitHub App instead of an OAuth app to use fine-grained permissions, gain more control over which repositories the application can access, and use short-lived tokens. + +.. link:https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app[Register a GitHub App] with the following configuration: + +GitHub App name:: +Enter a unique name identifying your GitHub App, such as `integrating-with-rhdh-____`. + +Homepage URL:: +Enter your {product-short} URL: `pass:c,a,q[{my-product-url}]`. + +Authorization callback URL:: +Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`. + +Webhook:: +Clear "Active", as this is not needed for authentication and catalog providers. + +App permissions:: +Select permissions to define the level of access for the app. +Adapt permissions to your needs: + +Reading software components::: + +Contents:::: +`Read-only` + +Commit statuses:::: +`Read-only` + +Reading organization data::: + +Members:::: +`Read-only` + +Publishing software templates::: +Set permissions if you intend to use the same GitHub App for software templates. + +Administration:::: +`Read & write` (for creating repositories) + +Contents:::: +`Read & write` + +Metadata:::: +`Read-only` + +Pull requests:::: +`Read & write` + +Issues:::: +`Read & write` + +Workflows:::: +`Read & write` (if templates include GitHub workflows) + +Variables:::: +`Read & write` (if templates include GitHub Action Repository Variables) + +Secrets:::: +`Read & write` (if templates include GitHub Action Repository Secrets) + +Environments:::: +`Read & write` (if templates include GitHub Environments) + +Organization permissions:: +Members::: +`Read-only` + +Where can this GitHub App be installed?:: +Select `Only on this account`. + +.. In the *General* -> *Clients secrets* section, click *Generate a new client secret*. + +.. In the *General* -> *Private keys* section, click *Generate a private key*. + +.. In the *Install App* tab, choose an account to install your GitHub App on. + +.. Save the following values for the next step: + +* **App ID** +* **Client ID** +* **Client secret** +* **Private key** diff --git a/modules/configuring/proc-provisioning-your-custom-configuration.adoc b/modules/configuring/proc-provisioning-your-custom-configuration.adoc index f4f41608fe..44bfc617f4 100644 --- a/modules/configuring/proc-provisioning-your-custom-configuration.adoc +++ b/modules/configuring/proc-provisioning-your-custom-configuration.adoc @@ -12,50 +12,42 @@ Your changes on this configuration might get reverted on {product-short} restart .Prerequisites * By using the link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/cli_tools/index#cli-about-cli_cli-developer-commands[{openshift-cli}], you have access, with developer permissions, to the {ocp-short} cluster aimed at containing your {product-short} instance. +include::snip-provisioning-your-custom-configuration-prerequisites-in-{context}-context.adoc[] + .Procedure -. Author your custom `__.txt` file to provision your secrets as environment variables values in an {ocp-short} secret, rather than in clear text in your configuration files. -It contains one secret per line in `KEY=value` form. +. For security, store your secrets as environment variables values in an {ocp-short} secret, +rather than in clear text in your configuration files. +Collect all your secrets in the `secrets.txt` file, with one secret per line in `KEY=value` form. + -* link:{authentication-book-url}[Enter your authentication secrets]. +-- +include::snip-provisioning-your-custom-configuration-secrets-step-in-{context}-context.adoc[] +-- . Author your custom `{my-app-config-file}` file. This is the main {product-short} configuration file. You need a custom `{my-app-config-file}` file to avoid the {product-short} installer to revert user edits during upgrades. When your custom `{my-app-config-file}` file is empty, {product-short} is using default values. ++ +-- +include::snip-provisioning-your-custom-configuration-appconfig-step-in-{context}-context.adoc[] +-- -** To prepare a deployment with the {product} Operator on {ocp-short}, you can start with an empty file. - -** To prepare a deployment with the {product} Helm chart, or on Kubernetes, enter the {product-short} base URL in the relevant fields in your `{my-app-config-file}` file to ensure proper functionality of {product-short}. -The base URL is what a {product-short} user sees in their browser when accessing {product-short}. -The relevant fields are `baseUrl` in the `app` and `backend` sections, and `origin` in the `backend.cors` subsection: +. Author your custom `dynamic-plugins.yaml` file to enable plugins. +By default, {product-short} enables a minimal plugin set, and disables plugins that require configuration or secrets, such as the GitHub repository discovery plugin and the Role-based access control (RBAC) plugin. + -.Configuring the `baseUrl` in `{my-app-config-file}` -==== -[source,yaml,subs="+attributes,+quotes"] +Enable the GitHub repository discovery and the RBAC features: ++ +.`dynamic.plugins.yaml` +[source,yaml] ---- -app: - title: {product} - baseUrl: {my-product-url} - -backend: - auth: - externalAccess: - - type: legacy - options: - subject: legacy-default-config - secret: "${BACKEND_SECRET}" - baseUrl: {my-product-url} - cors: - origin: {my-product-url} +includes: + - dynamic-plugins.default.yaml +plugins: + - package: ./dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github + disabled: false + - package: ./dynamic-plugins/dist/backstage-community-plugin-rbac + disabled: false ---- -==== - -** Optionally, enter your configuration such as: - -*** link:{authentication-book-url}[{authentication-book-title}]. -*** link:{authorization-book-url}[{authorization-book-title}]. -*** link:{customizing-book-url}[Customization]. -*** xref:proc-configuring-an-rhdh-instance-with-tls-in-kubernetes_running-behind-a-proxy[Configure your {ocp-short} integration]. . Provision your custom configuration files to your {ocp-short} cluster. @@ -68,36 +60,25 @@ $ oc create namespace {my-product-namespace} + Alternatively, link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/building_applications/index#creating-a-project-using-the-web-console_projects[create the project by using the web console]. -.. Provision your `{my-app-config-file}` file to the `{my-app-config-config-map}` config map in the _<{my-product-namespace}>_ project. +.. Provision your `{my-app-config-file}` and `dynamic-plugins.yaml` files respectively to the `{my-app-config-config-map}` and `dynamic-plugins-rhdh` config maps in the _<{my-product-namespace}>_ project. + [source,terminal,subs="+attributes,+quotes"] ---- $ oc create configmap {my-app-config-config-map} --from-file={my-app-config-file} --namespace={my-product-namespace} +$ oc create configmap dynamic-plugins-rhdh --from-file=dynamic-plugins.yaml --namespace={my-product-namespace} ---- + -Alternatively, link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nnodes-pods-configmap-create-from-console_configmaps[create the config map by using the web console]. +Alternatively, +link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nnodes-pods-configmap-create-from-console_configmaps[create the config maps by using the web console]. -.. Provision your `__.txt` file to the `__` secret in the _<{my-product-namespace}>_ project. +.. Provision your `secrets.txt` file to the `{my-product-secrets}` secret in the _<{my-product-namespace}>_ project. + [source,terminal,subs="+attributes,+quotes"] ---- -$ oc create secret generic `__` --from-file=`__.txt` --namespace={my-product-namespace} +$ oc create secret generic {my-product-secrets} --from-file=secrets.txt --namespace={my-product-namespace} ---- + Alternatively, link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/nodes/index#nodes-pods-secrets-creating-web-console-secrets_nodes-pods-secrets[create the secret by using the web console]. -[NOTE] -==== -`__` is your preferred {product-short} secret name, specifying the identifier for your secret configuration within {product-short}. -==== - -.Next steps -Consider provisioning additional config maps and secrets: - -* To use an external PostgreSQL database, xref:configuring-external-postgresql-databases[provision your PostgreSQL database secrets]. - - -* To enable dynamic plugins, link:{installing-and-viewing-plugins-book-url}[provision your dynamic plugins config map]. - -* To configure authorization by using external files, link:{authorization-book-url}#managing-authorizations-by-using-external-files[provision your RBAC policies config map]. +include::snip-provisioning-your-custom-configuration-next-steps-in-{context}-context.adoc[] diff --git a/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc b/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc new file mode 100644 index 0000000000..e6c3f4d7c6 --- /dev/null +++ b/modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc @@ -0,0 +1,71 @@ +[id="using-the-operator-to-run-rhdh-with-your-custom-configuration"] += Using the {product} Operator to run {product-short} with your custom configuration + +To use the {product-short} Operator to run {product} with your custom configuration, create your {product-custom-resource-type} custom resource (CR) that: + +* Mounts files provisioned in your custom config maps. +* Injects environment variables provisioned in your custom secrets. + +.Prerequisites +* By using the link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/cli_tools/index#cli-about-cli_cli-developer-commands[{openshift-cli}], you have access, with developer permissions, to the {ocp-short} cluster aimed at containing your {product-short} instance. +* xref:proc-install-operator_getting-started-with-rhdh-on-ocp-for-the-platform-engineer[] +* xref:provisioning-your-custom-configuration[] + +.Procedure + +. Author your {product-custom-resource-type} CR in a `{my-product-cr-name}.yaml` file to use your custom config maps and secrets. ++ +.`{my-product-cr-name}.yaml` custom resource example with dynamic plugins and RBAC policies config maps, and external PostgreSQL database secrets. +[source,yaml,subs="+attributes,+quotes"] +---- +apiVersion: rhdh.redhat.com/v1alpha3 +kind: Backstage +metadata: + name: _<{my-product-cr-name}>_ +spec: + application: + appConfig: + mountPath: /opt/app-root/src + configMaps: + - name: {my-app-config-config-map} + - name: rbac-policies + dynamicPluginsConfigMapName: dynamic-plugins-rhdh + extraEnvs: + envs: + - name: HTTP_PROXY + value: 'http://10.10.10.105:3128' + - name: HTTPS_PROXY + value: 'http://10.10.10.106:3128' + - name: NO_PROXY + value: 'localhost,example.org' + secrets: + - name: {my-product-secrets} + extraFiles: + mountPath: /opt/app-root/src + secrets: + - name: {my-product-database-certificates-secrets} + key: postgres-crt.pem, postgres-ca.pem, postgres-key.key + replicas: 2 + database: + enableLocalDb: false +---- + +`application`:: +`appConfig`::: Register your `{my-app-config-config-map}` and `rbac-policies` config maps. +`dynamicPluginsConfigMapName`::: Register your `dynamic-plugins-rhdh` config map. +`extraEnvs`::: +`env`:::: Enter your proxy environment variables. +`secrets`:::: Register your `` and `{my-product-database-secrets}` secrets. +`extraFiles`::: +`secrets`:::: +Register the `postgres-crt.pem`, `postgres-ca.pem`, and `postgres-key.key` files contained in the `{my-product-database-certificates-secrets}` secret. +`replicas`::: Enable high availability (HA) by increasing the replicas count to a value higher or equal to 2. +`database`:: +`enableLocalDb`::: Use your external PostgreSQL database rather than the internal PostgreSQL database. + +. Apply your {product-custom-resource-type} CR to start or update your {product-short} instance. ++ +[source,terminal,subs="+attributes,+quotes"] +---- +$ oc apply --filename={my-product-cr-name}.yaml --namespace={my-product-namespace} +---- diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc new file mode 100644 index 0000000000..bab219ef81 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc @@ -0,0 +1,70 @@ +.. For a production environment start with: ++ +.`{my-app-config-file}` +[source,yaml,subs="+attributes,+quotes"] +---- +app: + title: _<{product}>_ + branding: + fullLogo: ${BASE64_EMBEDDED_FULL_LOGO} + fullLogoWidth: 110px + iconLogo: ${BASE64_EMBEDDED_ICON_LOGO} +backend: + cache: + store: redis + connection: ${REDIS_CONNECTION} +techdocs: + cache: + ttl: 3600000 +catalog: + providers: + github: + providerId: + organization: "${GITHUB_INTEGRATION_ORGANIZATION}" + schedule: + frequency: + minutes: 30 + initialDelay: + seconds: 15 + timeout: + minutes: 15 +integrations: + github: + - host: ${GITHUB_INTEGRATION_HOST_DOMAIN} + apps: + - appId: ${GITHUB_INTEGRATION_APP_ID} + clientId: ${GITHUB_INTEGRATION_CLIENT_ID} + clientSecret: ${GITHUB_INTEGRATION_CLIENT_SECRET} + privateKey: | + ${GITHUB_INTEGRATION_PRIVATE_KEY_FILE} +permission: + enabled: true + rbac: + admin: + users: + - name: user:default/ + pluginsWithPermission: + - catalog + - scaffolder + - permission +---- +Most fields use environment variables that you defined in secrets in the previous step. +`app`:: +`title`::: Enter your Developer Hub instance display name, such as _<{product}>_. +`branding`::: Set your custom logo. ++ +Optionally, customize the width of the branding logo by changing value for the `fullLogoWidth` field. The following units are supported: integer, px, em, rem, percentage. +`backend`:: +`cache`::: Enable the plugins assets cache. +`techdocs`:: +`cache`::: Enable the Techdocs cache. +`catalog`:: +`provider`::: +`github`:::: Enable GitHub repository discovery. +`integrations`:: +`github`::: Enable GitHub repository discovery. +[id='enabling-and-giving-access-to-rbac'] +`permissions`:: Enable Role-based access control. +Enter your policy administrator name. + +.. Additionally, link:{authentication-book-url}[provision users and enabling authentication with your external identity provider]. diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-in-provisioning-and-using-your-custom-configuration-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-in-provisioning-and-using-your-custom-configuration-context.adoc new file mode 100644 index 0000000000..6e5ab9ef70 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-appconfig-step-in-provisioning-and-using-your-custom-configuration-context.adoc @@ -0,0 +1,35 @@ + +** To prepare a deployment with the {product} Operator on {ocp-short}, you can start with an empty file. + +** To prepare a deployment with the {product} Helm chart, or on Kubernetes, enter the {product-short} base URL in the relevant fields in your `{my-app-config-file}` file to ensure proper functionality of {product-short}. +The base URL is what a {product-short} user sees in their browser when accessing {product-short}. +The relevant fields are `baseUrl` in the `app` and `backend` sections, and `origin` in the `backend.cors` subsection: ++ +.Configuring the `baseUrl` in `{my-app-config-file}` +==== +[source,yaml,subs="+attributes,+quotes"] +---- +app: + title: {product} + baseUrl: {my-product-url} + +backend: + auth: + externalAccess: + - type: legacy + options: + subject: legacy-default-config + secret: "${BACKEND_SECRET}" + baseUrl: {my-product-url} + cors: + origin: {my-product-url} +---- +==== + +** Optionally, enter your configuration such as: + +*** link:{authentication-book-url}[{authentication-book-title}]. +*** link:{authorization-book-url}[{authorization-book-title}]. +*** link:{customizing-book-url}[Customization]. +*** xref:configuring-an-rhdh-instance-with-tls-in-kubernetes[Configure your {ocp-short} integration]. + diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc new file mode 100644 index 0000000000..89784779c0 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc @@ -0,0 +1,6 @@ +.. Provision your PosgreSQL TLS certificates to the `{my-product-database-secrets}` secret in the _<{my-product-namespace}>_ project. ++ +[source,terminal,subs="+attributes,+quotes"] +---- +$ oc create secret generic {my-product-secrets} --from-file=postgres-ca.pem --from-file=postgres-crt.pem --from-file=postgres-key.key --namespace={my-product-namespace} +---- diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-provisioning-and-using-your-custom-configuration-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-provisioning-and-using-your-custom-configuration-context.adoc new file mode 100644 index 0000000000..f322c0a764 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-next-steps-in-provisioning-and-using-your-custom-configuration-context.adoc @@ -0,0 +1,9 @@ +.Next steps +Consider provisioning additional config maps and secrets: + +* To use an external PostgreSQL database, xref:configuring-external-postgresql-databases[provision your PostgreSQL database secrets]. + + +* To enable dynamic plugins, link:{installing-and-viewing-plugins-book-url}[provision your dynamic plugins config map]. + +* To configure authorization by using external files, link:{authorization-book-url}#managing-authorizations-by-using-external-files[provision your RBAC policies config map]. diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-prerequisites-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-prerequisites-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc new file mode 100644 index 0000000000..f3d1062c61 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-prerequisites-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc @@ -0,0 +1,25 @@ +* You have the connection string to an active Redis server, such as `rediss://user:pass@cache.example.com:6379`. +For security, consider using a `rediss` secure server connection. +See xref:preparing-your-external-services[]. +* You have an external PostgreSQL database, with the following details. +See See xref:preparing-your-external-services[]. + +postgres-host::: Your PostgreSQL instance Domain Name System (DNS) or IP address. +postgres-port::: Your PostgreSQL instance port number, such as 5432. +postres-username::: The user name to connect to your PostgreSQL instance. +postgres-password::: The password to connect to your PostgreSQL instance. +postgres-ca.pem::: +postgres-key.key::: +postgres-crt.pem::: +TLS certificates to secure the connection to the database. + +* You have a GitHub App enabling access to the GitHub API for repository discovery, with the following details. +See See xref:preparing-your-external-services[]. +GITHUB_INTEGRATION_APP_ID::: +Your GitHub integration App ID. +GITHUB_INTEGRATION_CLIENT_ID::: +Your GitHub integration App client ID. +GITHUB_INTEGRATION_CLIENT_SECRET::: +Your GitHub integration App client secret. +GITHUB_INTEGRATION_PRIVATE_KEY_FILE::: +Your GitHub integration App private key. diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-prerequisites-in-provisioning-and-using-your-custom-configuration-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-prerequisites-in-provisioning-and-using-your-custom-configuration-context.adoc new file mode 100644 index 0000000000..e69de29bb2 diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-secrets-step-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-secrets-step-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc new file mode 100644 index 0000000000..55530b97d9 --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-secrets-step-in-getting-started-with-rhdh-on-ocp-for-the-platform-engineer-context.adoc @@ -0,0 +1,51 @@ +.. Enter your custom logo. ++ +[source,subs="+attributes,+quotes"] +---- +BASE64_EMBEDDED_FULL_LOGO="data:image/svg+xml;base64," +BASE64_EMBEDDED_ICON_LOGO="data:image/svg+xml;base64," +---- +`BASE64_EMBEDDED_FULL_LOGO`:: +Enter your logo for the expanded (pinned) sidebar as a base64 encoded SVG image. ++ +To encode your logo in base64, run: ++ +[source] +---- +$ base64 -i logo.svg +---- +`BASE64_EMBEDDED_ICON_LOGO`:: +Enter your logo for the collapsed (unpinned) sidebar as a base64 encoded SVG image. + +.. Enter the connection string to your Redis server that caches plugin assets. ++ +[source] +---- +REDIS_CONNECTION=rediss://user:pass@cache.example.com:6379 +---- + +.. Enter your GitHub integration credentials: ++ +[source,subs="+quotes"] +---- +GITHUB_INTEGRATION_APP_ID=___ +GITHUB_INTEGRATION_CLIENT_ID=__ +GITHUB_INTEGRATION_CLIENT_SECRET=__ +GITHUB_INTEGRATION_HOST_DOMAIN=github.com +GITHUB_INTEGRATION_ORGANIZATION=__ +GITHUB_INTEGRATION_PRIVATE_KEY_FILE= __ +---- + +.. Enter your PosgreSQL database secrets: ++ +[source,subs="+quotes"] +---- +POSTGRES_PASSWORD: +POSTGRES_PORT: "" +POSTGRES_USER: +POSTGRES_HOST: +PGSSLMODE: verify-full +NODE_EXTRA_CA_CERTS: /opt/app-root/src/postgres-crt.pem +---- + +.. link:{authentication-book-url}[Enter your authentication secrets]. diff --git a/modules/configuring/snip-provisioning-your-custom-configuration-secrets-step-in-provisioning-and-using-your-custom-configuration-context.adoc b/modules/configuring/snip-provisioning-your-custom-configuration-secrets-step-in-provisioning-and-using-your-custom-configuration-context.adoc new file mode 100644 index 0000000000..b6c7d748fe --- /dev/null +++ b/modules/configuring/snip-provisioning-your-custom-configuration-secrets-step-in-provisioning-and-using-your-custom-configuration-context.adoc @@ -0,0 +1 @@ +* link:{authentication-book-url}[Enter your authentication secrets]. diff --git a/modules/installation/proc-install-operator.adoc b/modules/installation/proc-install-operator.adoc index 02c0e58f1b..888f7a68a1 100644 --- a/modules/installation/proc-install-operator.adoc +++ b/modules/installation/proc-install-operator.adoc @@ -83,8 +83,3 @@ If you selected an *Automatic* approval strategy, the upgrade status should reso *** From the list of installed Operators, locate the {product} Operator name and details. *** Click *{product} Operator* to open the *Operator details* page for the {product} Operator. -[role="_additional-resources"] -.Additional resources - -* xref:proc-install-rhdh-ocp-operator_{context}[Deploying {product} on {ocp-short} with the Operator] -* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{ocp-version}/html-single/operators/index#olm-installing-from-operatorhub-using-web-console_olm-adding-operators-to-a-cluster[Installing from OperatorHub by using the web console] diff --git a/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc b/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc index de0ff31dcf..6729054dd2 100644 --- a/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc +++ b/modules/integrating-with-github/proc-enabling-github-repository-discovery.adoc @@ -25,7 +25,7 @@ Authorization callback URL:: Enter your {product-short} authentication backend URL: `pass:c,a,q[{my-product-url}/api/auth/github/handler/frame]`. Webhook:: -Clear "Active", as this is not needed for authentication and catalog providers. +Clear "Active", as this is not needed for authentication and catalog providers. App permissions:: Select permissions to define the level of access for the app. @@ -117,7 +117,7 @@ It provides an automated alternative to manually registering components via `cat When a repository contains a `catalog-info.yaml` file, the entity is ingested into the catalog as a component. + .`dynamic-plugins.yaml` file fragment -[code,yaml] +[source,yaml] ---- plugins: - package: './dynamic-plugins/dist/backstage-plugin-catalog-backend-module-github' diff --git a/titles/configuring/master.adoc b/titles/configuring/master.adoc index d912fc4eec..e11c1a510a 100644 --- a/titles/configuring/master.adoc +++ b/titles/configuring/master.adoc @@ -27,7 +27,7 @@ include::assemblies/assembly-configuring-high-availability.adoc[leveloffset=+1] include::assemblies/assembly-configuring-a-proxy.adoc[leveloffset=+1] -include::modules/installation/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc[leveloffset=+1] +include::modules/configuring/proc-configuring-an-rhdh-instance-with-tls-in-kubernetes.adoc[leveloffset=+1] include::assemblies/dynamic-plugins/assembly-using-the-dynamic-plugins-cache.adoc[ leveloffset=+1] @@ -36,4 +36,4 @@ include::assemblies/dynamic-plugins/assembly-using-the-dynamic-plugins-cache.ado include::assemblies/assembly-configuring-default-secret-pvc-mounts.adoc[leveloffset=+1] -include::modules/configuring/proc-enabling-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1] \ No newline at end of file +include::modules/configuring/proc-enabling-the-rhdh-plugin-assets-cache.adoc[leveloffset=+1] diff --git a/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc b/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc index 49146153cf..0d4466fced 100644 --- a/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc +++ b/titles/getting-started-with-rhdh-on-ocp-for-the-platform-engineer/master.adoc @@ -1,10 +1,56 @@ include::artifacts/attributes.adoc[] :title: Getting started with {product} on {ocp-brand-name} for the platform engineer :subtitle: As a platform engineer, prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production. -:abstract: As a platform engineer, prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production. -:context: customizing-display +:abstract: As a platform engineer, prepare your IT infrastructure including {ocp-brand-name} and required external components, and run your first {product} ({product-very-short}) instance in production with an adapted secure, efficient, and resilient configuration. +:context: getting-started-with-rhdh-on-ocp-for-the-platform-engineer [id="{context}"] = {title} {abstract} +With the default configuration, {product-short} runs with a minimal feature set that does not require to securely connect to external services such as an identity provider, a Git provider, and external PostgreSQL and Redis databases. +Therefore using critical features require configuration: + +For resiliency:: +* Use an external PostgreSQL database. +* Enable high-availability. + +For performance:: +* Enable assets caching to an external Redis database. + +For security:: +* Use secure connections to your external services. +* Provision users and enable authentication. +* Enable role-based access control, and configure the permission policy by using the Web UI. + +For your environment:: +* Enable GitHub repository discovery. +* Customize {product-short} appearance with your logo. + +// Install the operator +include::modules/installation/proc-install-operator.adoc[leveloffset=+1] + +include::modules/configuring/proc-preparing-your-external-services.adoc[leveloffset=+1] + +// Provision your custom configuration +include::modules/configuring/proc-provisioning-your-custom-configuration.adoc[leveloffset=+1] + +// TODO: Understand the software catalog + +// Authentication: simplified +// FIXME: see https://github.com/redhat-developer/red-hat-developers-documentation-rhdh/pull/1266 + +include::modules/configuring/proc-using-the-operator-to-run-rhdh-with-your-custom-configuration-in-getting-started-context.adoc[leveloffset=+1] + +include::modules/customizing-the-appearance/proc-customize-rhdh-theme-mode.adoc[leveloffset=+1] + +include::assemblies/assembly-managing-authorizations-by-using-the-rhdh-web-ui.adoc[leveloffset=+1] + +// Importing manually a Git repository +// FIXME: To do + +// Run a CI pipeline: GitHub; CF + Tekton +// FIXME : To do + +// Configure Software Templates +// FIXME : To do