K8SPS-689 Documented the new connection secret (#219)

* K8SPS-689 Documented the new connection secret

Updated relevant docs
Created a new doc with filed reference and examples

* Added CustomDNSSuffix description

Author: nastena1606

.cursor/agents/release-notes-changelog.md

@@ -0,0 +1,131 @@
+---
+name: release-notes-changelog
+description: Updates the Changelog section in Percona Operator release notes from a Jira issues file. Converts technical Jira details into clear, user-focused release note bullets. Use proactively when preparing or updating release notes for a new version.
+---
+
+You update the **Changelog** section in Percona Operator release notes markdown files. Your primary objective is to convert technical details from Jira issues into clear, concise, and user-focused release notes.
+
+## When invoked
+
+1. Identify the **Jira issues source file** (user-provided path, or ask if missing).
+2. Identify the **target release notes file** (user-provided path, or the latest file in `docs/ReleaseNotes/` matching `Kubernetes-Operator-for-PS-RN*.md`). Ask if missing or unsure.
+3. Read every issue in the source file (key, summary, description, issue type, and any reporter/thank-you notes).
+4. Classify each issue into a changelog section (see below). **Exclude** epics and administrative tasks.
+5. Write or replace the `## Changelog` section in the target file. Preserve all other content in the release notes file unchanged.
+6. Show the user the updated Changelog section and confirm which file was modified.
+
+## Repository context
+
+| Product | Release notes directory | Jira base URL |
+|---------|------------------------|---------------|
+| PS Operator (this repo) | `docs/ReleaseNotes/` | `https://perconadev.atlassian.net/browse/` |
+| PXC Operator | `docs/ReleaseNotes/` | `https://perconadev.atlassian.net/browse/` |
+| PSMDB Operator | `docs/RN/` | `https://perconadev.atlassian.net/browse/` |
+| PG Operator | `docs/ReleaseNotes/` | `https://perconadev.atlassian.net/browse/` |
+
+Build issue links as `{Jira base URL}{KEY}` (example: `https://perconadev.atlassian.net/browse/K8SPS-410`).
+
+## Section organization
+
+Organize the Changelog into these sections **in this exact order**. Omit any section that has no items.
+
+1. `### New Features`
+2. `### Improvements`
+3. `### Bug Fixes`
+
+### Issue type mapping
+
+| Jira issue type | Changelog section |
+|-----------------|-------------------|
+| Story, New Feature, Feature | New Features |
+| Improvement, Enhancement, Task (non-admin) | Improvements |
+| Bug, Defect | Bug Fixes |
+
+### Exclusions — do not include
+
+- Epics
+- Administrative tasks (release planning, CI/CD housekeeping, internal tooling, documentation-only meta tasks unless the user explicitly asks to include them)
+- Duplicate keys
+- Issues marked as won't fix, duplicate, or not a release item unless the user says otherwise
+
+When unsure whether a Task is user-facing, prefer **Improvements** if it affects operator behavior, cluster lifecycle, backups, monitoring, or configuration; otherwise exclude it.
+
+## Bullet format (strict)
+
+Every item must follow this structure exactly:
+
+```markdown
+* [KEY](Link): Summary. Description.
+```
+
+Rules:
+
+- Start with `*` (asterisk bullet).
+- Link the issue key: `[K8SPS-410](https://perconadev.atlassian.net/browse/K8SPS-410)`.
+- Use a **dash** after the closing parenthesis, then a space.
+- **Do not bold** the summary text.
+- Leave a blank line between bullet items (match existing release notes style in the repo).
+
+### Two-sentence rule (strict)
+
+Each item must contain **exactly two sentences**, separated by a period and space:
+
+1. **Sentence 1:** What was added, improved, or fixed, and its immediate benefit or impact for the user or administrator.
+2. **Sentence 2:** Underlying technical context, root cause, or the precise behavioral change from a user-value perspective.
+
+Do not write one-sentence or three-or-more-sentence items. Do not use semicolons to cram extra clauses into a single sentence.
+
+### User-value centric writing
+
+- Focus on how the change helps users or administrators: preventing downtime, saving storage, reducing monitoring noise, simplifying configuration, improving recovery, etc.
+- Translate raw error messages, stack traces, and internal component names into plain language.
+- Mention Custom Resource fields, environment variables, or operator behavior only when they help the reader act on the change.
+- Preserve reporter thank-you notes when present in the Jira data, appended at the end of sentence 2 in parentheses: `(Thank you Name for reporting this issue)`.
+
+### Examples
+
+**New Features:**
+
+```markdown
+* [K8SPS-410](https://perconadev.atlassian.net/browse/K8SPS-410) - Added incremental backups so you can capture only changes since the previous backup. This reduces backup size, storage use, and transfer time while lowering load on the cluster during frequent backup jobs.
+```
+
+**Improvements:**
+
+```markdown
+* [K8SPS-69](https://perconadev.atlassian.net/browse/K8SPS-69) -  Updated the readiness probe to fail when replication threads have stopped. Application traffic is no longer routed to replicas that are not receiving updates from the primary, which prevents stale reads during replication interruptions.
+```
+
+**Bug Fixes:**
+
+```markdown
+* [K8SPS-530](https://perconadev.atlassian.net/browse/K8SPS-530) - Fixed an issue where the delete-backup finalizer blocked removal of backups stuck in the starting state. You can now delete pending or failed backup resources immediately instead of waiting for a timeout.
+```
+
+## Editing the release notes file
+
+1. Locate the existing `## Changelog` heading in the target file.
+2. Replace everything from `## Changelog` up to (but not including) the next `##` heading (typically `## Supported software`).
+3. If no Changelog section exists, insert one before `## Supported software` or at the end of the narrative sections.
+4. Do **not** modify Release highlights, CRD changes, Supported software, Supported platforms, or Percona certified images unless the user explicitly asks.
+
+## Quality checklist
+
+Before finishing, verify:
+
+- [ ] Sections appear in order: New Features → Improvements → Bug Fixes
+- [ ] Every bullet uses `* [KEY](Link) - Summary. Description.` format with a dash
+- [ ] No summary text is bolded
+- [ ] Every item has exactly two sentences
+- [ ] No epics or administrative tasks included
+- [ ] Language is user-focused, not a paste of Jira technical notes
+- [ ] Blank line between each bullet item
+- [ ] All other release notes content is unchanged
+
+## Output
+
+After updating the file, briefly summarize:
+
+- Target release notes file path
+- Number of items per section
+- Any issues excluded and why (epic, admin, duplicate, unclear type)

docs/assets/fragments/connectivity.txt

@@ -1,44 +1,42 @@
-To connect to Percona Server for MySQL you will need the password for the root user. Passwords are stored in the [Secrets :octicons-link-external-16:](https://kubernetes.io/docs/concepts/configuration/secret/) object, which was generated during the previous steps.
+To connect to Percona Server for MySQL, use the connection Secret that the Operator creates for the `root` user. It is named `<cluster_name>-psuser-root` (by default, `ps-cluster1-psuser-root`) and contains hostnames, ports, credentials, and ready-to-use connection URIs. Read [Connection secrets](connection-secrets.md) for the full reference.
 
-Here’s how to get it:
+Here's how to connect:
 
-1. List the Secrets objects.
+1. Export the namespace, cluster name and the Secret name as environment variables:
 
-    ```{.bash data-prompt="$"}
-    $ {{ commandName }} get secrets
+    ```bash
+    export NAMESPACE=my-namespace
+    export CLUSTER_NAME=ps-cluster1
+    export SECRET_NAME=${CLUSTER_NAME}-psuser-root
     ```
-    It will show you the list of Secrets objects (by default the Secrets object you are interested in has `ps-cluster1-secrets` name).
 
-2. Use the following command to get the password of the `root` user.  Substitute `ps-cluster1` with your value, if needed:
-    
+    Replace `ps-cluster1` with the [name of your cluster](operator.md#metadata-name) if you changed it during installation.
+
+2. List the Secrets objects.
+
     ```{.bash data-prompt="$"}
-    $ {{ commandName }} get secret ps-cluster1-secrets -o yaml
-    ```
-    
-    The command returns the YAML file with generated Secrets, including the `root` password, which
-    should look as follows:
-
-    ```{.yaml .no-copy}
-    ...
-    data:
-      ...
-      root: <base64-encoded-password>
+    $ {{ commandName }} get secrets -n $NAMESPACE
     ```
 
-3. The actual password is base64-encoded. Use the following command to bring it
-    back to a human-readable form:
+    Look for the Secret named `<cluster_name>-psuser-root`. By default, it is `ps-cluster1-psuser-root`.
 
-    ```{.bash data-prompt="$"}
-    $ echo '<base64-encoded-password>' | base64 --decode
+3. Retrieve the user credentials from the Secret:
+   
+    ```bash
+{{ commandName }} get secret "$SECRET_NAME" -n "$NAMESPACE" \
+  -o jsonpath='{.data.user}' | base64 --decode && echo
+{{ commandName }} get secret "$SECRET_NAME" -n "$NAMESPACE" \
+  -o jsonpath='{.data.password}' | base64 --decode && echo
     ```
 
-4. Run a container with `mysql` tool and connect its console output to your terminal. The following command will do this, naming the new Pod `percona-client`:
 
-    ```{.bash data-prompt="$"}
-    $ {{ commandName }} run -i --rm --tty percona-client --image=percona/percona-server:8.4 --restart=Never -- bash -il
+4. Run a container with the `mysql` tool and connect its console output to your terminal:
+
+    ```bash
+    {{ commandName }} run -i --rm --tty percona-client --image=percona/percona-server:8.4 --restart=Never -- bash -il
     ```
 
-    It may require some time to execute the command and deploy the correspondent Pod.
+    It may require some time to execute the command and deploy the corresponding Pod.
 
 5. Now run `mysql` tool in the `percona-client` command shell using the password
     obtained from the Secret instead of the `<root password>` placeholder.
@@ -47,11 +45,13 @@ Here’s how to get it:
     [MySQL Router](router-conf.md) (can be used with Group Replication clusters):
 
     === "If using HAProxy (default)"
+
         ``` bash
         mysql -h ps-cluster1-haproxy -uroot -p<root password>
         ```
 
     === "If using MySQL Router"
+    
         ```bash
         mysql -h ps-cluster1-router -uroot -p<root password>
         ```
@@ -95,4 +95,3 @@ Here’s how to get it:
 
         mysql> 
         ```
-

docs/connect.md

@@ -2,56 +2,71 @@
 
 In this tutorial, you will connect to the Percona Server for MySQL you deployed previously.
 
-To connect to Percona Server for MySQL you will need the password for the `root` user. Passwords are stored in the Secrets object. 
+The Operator creates a dedicated Secret named `<cluster_name>-psuser-root` that contains all connection details for the `root` user: hostname, port, username, password, and ready-to-use URIs. The Operator keeps this Secret up to date on every reconciliation. 
 
-Here's how to get it:
+Here's how to connect:
 {.power-number}
 
-1. List the Secrets objects
+1. Export the namespace, cluster name and the Secret name as environment variables:
 
     ```bash
-    kubectl get secrets -n <namespace>
+    export NAMESPACE=my-namespace
+    export CLUSTER_NAME=ps-cluster1
+    export SECRET_NAME=${CLUSTER_NAME}-psuser-root
     ```
 
-    The Secrets object we target is named `<cluster_name>-secrets`. The `<cluster_name>` value is the [name of your Percona Server for MySQL](operator.md#metadata-name). The default variant for the Secrets object is:
+    Replace `ps-cluster1` with the [name of your cluster](operator.md#metadata-name) if you changed it during installation.
 
-    === "via kubectl" 
+2. Verify that the connection Secret exists:
 
-        `ps-cluster1-secrets`
+    ```bash
+    kubectl get secret $SECRET_NAME -n $NAMESPACE
+    ```
 
-    === "via Helm"
+    Look for the Secret named `<cluster_name>-psuser-root`. The
+    default name differs on how you installed the Operator:
+
+    === "via kubectl"
 
-        `ps-cluster1-ps-db-secrets`
+        `ps-cluster1-psuser-root`
 
-2. Retrieve the password for the root user. Replace the `secret-name` and `namespace` with your values in the following commands:
+    === "via Helm"
+
+        `my-db-ps-db-psuser-root`
 
+3. Retrieve the user credentials from the Secret:
+   
     ```bash
-    kubectl get secret <secret-name> -n <namespace> --template='{{"{{"}}.data.root | base64decode{{"}}"}}{{"{{"}}"\n"{{"}}"}}'
+kubectl get secret "$SECRET_NAME" -n "$NAMESPACE" \
+  -o jsonpath='{.data.user}' | base64 --decode && echo
+kubectl get secret "$SECRET_NAME" -n "$NAMESPACE" \
+  -o jsonpath='{.data.password}' | base64 --decode && echo
     ```
 
-3. Run a container with `mysql` tool and connect its console output to your terminal. The following command does this, naming the new Pod `percona-client`:
+4. Run a container with the `mysql` client and connect its console output to your terminal. The following command does this, naming the new Pod `percona-client`:
 
     ```bash
-    kubectl run -n <namespace> -i --rm --tty percona-client \ 
+    kubectl run -n $NAMESPACE -i --rm --tty percona-client \
     --image=percona/percona-server:8.4 --restart=Never -- bash -il
     ```
 
     Executing it may require some time to deploy the corresponding Pod.
 
-4. Connect to Percona Server for MySQL. To do this, run `mysql` tool in the percona-client command shell using your cluster name and the password obtained from the secret instead of the `<root_password>` placeholder. The command will look different depending on whether your cluster  uses load balancing with [HAProxy](haproxy-conf.md) (the default behavior) or uses
-    [MySQL Router](router-conf.md) (can be used with Group Replication clusters only):
+5. Connect to Percona Server for MySQL. To do this, run `mysql` tool in the `percona-client` command shell using your cluster name and the password obtained from the secret instead of the `<root_password>` placeholder. The command will look different depending on whether your cluster  uses load balancing with [HAProxy](haproxy-conf.md) (the default behavior) or uses [MySQL Router](router-conf.md) (can be used with Group Replication clusters only):
 
     === "with HAProxy (default)"
+
         ```bash
         mysql -h <cluster_name>-haproxy -uroot -p'<root_password>'
         ```
 
     === "with MySQL Router"
+
         ```bash
         mysql -h <cluster_name>-router -uroot -p'<root_password>'
         ```
 
-Congratulations! You have connected to Percona Server for MySQL. 
+Congratulations! You have connected to Percona Server for MySQL.
 
 ## Next steps