docs

Author: Wachter, Julian

README.md

@@ -1,14 +1,14 @@
 # Provider keycloak
 `provider-keycloak` is an open-source [Crossplane](https://crossplane.io/) provider declaratively configuring [Keycloak](https://github.com/keycloak/keycloak).
-This provider is generated by using [Upjet](https://github.com/crossplane/upjet) building on the existing [Keycloak Terraform Provider](https://github.com/keycloak/terraform-provider-keycloak). 
+This provider is generated by using [Upjet](https://github.com/crossplane/upjet) building on the existing [Keycloak Terraform Provider](https://github.com/keycloak/terraform-provider-keycloak).
 It is installed into a Crossplane control plane and adds the following new functionality:
 
 * Custom Resource Definitions (CRDs) that model Keycloak configurations (e.g. realms, clients, roles, protocol mappers, etc.). You can see the full list of managed resources at the [marketplace](https://marketplace.upbound.io/providers/crossplane-contrib/provider-keycloak).
-* Controller to provision these resources in Keycloak based on the users desired state captured in CRDs they create. Reconciling them when the actual state and the desired states are drifting apart. 
+* Controller to provision these resources in Keycloak based on the users desired state captured in CRDs they create. Reconciling them when the actual state and the desired states are drifting apart.
 
 Check out the examples in the `examples` directory for more information on how to use this provider.
 
-## Usage 
+## Usage
 
 ### Installation
 
@@ -23,7 +23,7 @@ metadata:
   namespace: crossplane-system
 spec:
   package: xpkg.upbound.io/crossplane-contrib/provider-keycloak:<latest>
-``` 
+```
 
 This will install the provider in the `crossplane-system` namespace and install CRDs and controllers for the provider.
 Check https://marketplace.upbound.io/providers/crossplane-contrib/provider-keycloak for the lastet version
@@ -33,7 +33,7 @@ Check https://marketplace.upbound.io/providers/crossplane-contrib/provider-keycl
 We also support DeploymentRuntimeConfig to enable additional features in the provider.
 
 ```yaml
---- 
+---
 apiVersion: pkg.crossplane.io/v1beta1
 kind: DeploymentRuntimeConfig
 metadata:
@@ -70,7 +70,7 @@ spec:
 
 
 
-### Configuration 
+### Configuration
 
 - For each keycloak instance you need one or more `ProviderConfig` resources.
 - The `ProviderConfig` resource is used to store the keycloak API server URL, credentials, and other configuration details that are required to connect to the keycloak API server.
@@ -95,7 +95,7 @@ kind: Secret
 metadata:
   name: keycloak-credentials
   namespace: crossplane-system
-  labels: 
+  labels:
     type: provider-credentials
 type: Opaque
 stringData:
@@ -112,6 +112,15 @@ stringData:
 
 The secret `keycloak-credentials` contains the keycloak API server URL, credentials, and other configuration details that are required to connect to the keycloak API server. **It supports the same fields as the [terraform provider configuration](https://registry.terraform.io/providers/mrparkers/keycloak/latest/docs#argument-reference)**
 
+`url`, optional `admin_url`, and optional `base_path` are validated and normalized by this provider before configuring the Terraform provider:
+
+- `url` and `admin_url` must be absolute URLs with scheme and host (for example `https://keycloak.example.com`).
+- `url` and `admin_url` should not include query parameters or fragments.
+- Trailing `/` in `url` and `admin_url` is removed automatically.
+- `base_path` must be empty or start with `/` (for example `/auth`).
+- `base_path: "/"` is normalized to empty string to avoid double-slash request paths.
+- Trailing `/` in non-root `base_path` is removed automatically.
+
 As an alternative to using the embedded JSON format shown above, you can also place settings in a plain Kubernetes secret like this:
 
 ```yaml
@@ -135,14 +144,14 @@ stringData:
 
 ### Custom Resource Definitions
 
-You can explore the available custom resources: 
+You can explore the available custom resources:
 - [Upbound marketplace site](https://marketplace.upbound.io/providers/crossplane-contrib/provider-keycloak/)
 - `kubectl get crd | grep keycloak.crossplane.io` to list all the CRDs provided by the provider
 - `kubectl explain <CRD_NAME>` for docs on the CLI
 - You can also see the CRDs in the `package/crds` directory
 
 
-### Functions and Compositions: 
+### Functions and Compositions:
 
 - [function-keycloak-builtin-objects](https://gitlab.com/corewire/images/crossplane/function-keycloak-builtin-objects) - The function is used to import the builtin objects of a keycloak, e.g. clients and roles. Since v3.0 it also offers the possibility to adapt some default config. Everything you need to know is in the README of the repository.
 
@@ -196,8 +205,8 @@ TERRAFORM_PROVIDER_REPO=https://github.com/<owner>/terraform-provider-keycloak \
 TERRAFORM_PROVIDER_VERSION=1.0.0 \
 make generate
 ```
-**Hint:** `TERRAFORM_PROVIDER_VERSION` must be a Release. Releases can be found here: `https://github.com/<owner>/terraform-provider-keycloak/releases`. 
-Every ReleaseName should have the prefix "v" (i.e 'v1.0.0'). But if you specify the `TERRAFORM_PROVIDER_VERSION` you need to 
+**Hint:** `TERRAFORM_PROVIDER_VERSION` must be a Release. Releases can be found here: `https://github.com/<owner>/terraform-provider-keycloak/releases`.
+Every ReleaseName should have the prefix "v" (i.e 'v1.0.0'). But if you specify the `TERRAFORM_PROVIDER_VERSION` you need to
 skip that prefix (i.e. '1.0.0')
 
 2. Use forked repo as go dependency:
@@ -241,7 +250,7 @@ XPKG_REG_ORGS_NO_PROMOTE=xpkg.upbound.io/<owner> \
 make publish
 ```
 
-### Local Environment 
+### Local Environment
 Execute setup script which creates a KIND Cluster
 and installs crossplane, keycloak and the official crossplane provider
 via ArgoCD (for more options run script with `--help`)
@@ -361,7 +370,7 @@ This is used for marking an MR as test for automated tests. [Upjet based control
 
 2 - restart provider (scale down, scale up)
 
-3 - Clear `status.conditions` of all resources under test with 
+3 - Clear `status.conditions` of all resources under test with
 
 4 - Set `uptest-old-id` annotation of all resources under test to `.status.atProvider.id`
 
@@ -373,7 +382,7 @@ This is used for marking an MR as test for automated tests. [Upjet based control
 
 #### Delete Step
 
-1 - Delete all resources under test and wait for deletion 
+1 - Delete all resources under test and wait for deletion
 
 
 ### Add Tests
@@ -391,7 +400,7 @@ See more details [here](https://github.com/crossplane/uptest?tab=readme-ov-file#
 
 Define the available Versions of the resource and implement the [Conversion strategies](https://github.com/crossplane/upjet/blob/main/docs/managing-crd-versions.md#conversion-strategies).
 
-Here an example of a property renaming 
+Here an example of a property renaming
 ```go
 p.AddResourceConfigurator("xyz", func(r *config.Resource) {
     r.Version = "v1alpha2"

examples/credentials.yaml

@@ -12,5 +12,9 @@ stringData:
       "url": "https://keycloak.example.com",
       "base_path": "/auth",
       "realm": "master",
-      "root_ca_certificate" : "" 
-    }  
+      "root_ca_certificate" : ""
+    }
+
+# Notes:
+# - Do not set base_path to "/". Use empty string instead when Keycloak is mounted at root.
+# - url/admin_url should be absolute URLs without query/fragment.