diff --git a/.github/workflows/test-docs.yml b/.github/workflows/test-docs.yml index 1051a8a17d..7aab441434 100644 --- a/.github/workflows/test-docs.yml +++ b/.github/workflows/test-docs.yml @@ -11,6 +11,7 @@ jobs: runs-on: ubuntu-latest outputs: console: ${{ steps.filter.outputs.console }} + quickstart: ${{ steps.filter.outputs.quickstart }} steps: - name: Checkout code uses: actions/checkout@v4 @@ -21,22 +22,39 @@ jobs: filters: | console: - 'modules/console/**' + quickstart: + - 'modules/get-started/pages/quick-start.adoc' run-tests: needs: setup permissions: contents: write pull-requests: write issues: write + id-token: write strategy: matrix: os: [ubuntu-latest] # Only using Linux for now since macOS takes a long time runs-on: ${{ matrix.os }} steps: + - uses: aws-actions/configure-aws-credentials@v4 + with: + aws-region: ${{ vars.RP_AWS_CRED_REGION }} + role-to-assume: arn:aws:iam::${{ secrets.RP_AWS_CRED_ACCOUNT_ID }}:role/${{ vars.RP_AWS_CRED_BASE_ROLE_NAME }}${{ github.event.repository.name }} + - uses: aws-actions/aws-secretsmanager-get-secrets@v2 + with: + secret-ids: | + ,sdlc/prod/github/actions_bot_token + parse-json-secrets: true - uses: actions/checkout@v4 with: - token: ${{ secrets.GITHUB_TOKEN }} + token: ${{ env.ACTIONS_BOT_TOKEN }} path: redpanda-docs - - name: Test docs + + - name: Set GitHub token + run: | + echo "REDPANDA_GITHUB_TOKEN=${{ env.ACTIONS_BOT_TOKEN }}" >> $GITHUB_ENV + + - name: Run all tests if: ${{ github.event_name == 'workflow_dispatch' || github.event_name == 'repository_dispatch' }} uses: doc-detective/github-action@v1 with: @@ -46,11 +64,32 @@ jobs: # create a PR/issue only if the workflow wasn't already triggered by a PR create_pr_on_change: true create_issue_on_fail: true + token: ${{ env.ACTIONS_BOT_TOKEN }} - - name: Test Console docs + - name: Test Redpanda Console docs if: needs.setup.outputs.console == 'true' uses: doc-detective/github-action@v1 with: input: ../modules/console working_directory: redpanda-docs/setup-tests exit_on_fail: true + env: + REDPANDA_GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }} + + - name: Test Redpanda Self-Managed quickstart + if: needs.setup.outputs.quickstart == 'true' + uses: doc-detective/github-action@v1 + with: + input: ../modules/get-started/pages/quick-start.adoc + working_directory: redpanda-docs/setup-tests + exit_on_fail: true + env: + REDPANDA_GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }} + - name: Upload debug artifacts + if: failure() + uses: actions/upload-artifact@v4 + with: + name: doc-detective-output + path: /home/runner/work/_temp/doc-detective-output.json + env: + REDPANDA_GITHUB_TOKEN: ${{ env.ACTIONS_BOT_TOKEN }} diff --git a/antora.yml b/antora.yml index 00227f02a9..1709fcff9c 100644 --- a/antora.yml +++ b/antora.yml @@ -18,10 +18,15 @@ asciidoc: # We try to fetch the latest from GitHub at build time # -- full-version: 24.3.1 + latest-redpanda-tag: 'v24.3.1' + latest-console-tag: 'v2.7.2' latest-release-commit: '72ba3d3' latest-operator-version: 'v2.2.0-24.2.2' latest-redpanda-helm-chart-version: 5.8.3 - redpanda-beta-version: 24.3.1-rc2 + redpanda-beta-version: '24.3.1-rc2' + redpanda-beta-tag: 'v24.3.1-rc2' + console-beta-version: '2.8.0-beta.1' + console-beta-tag: 'v2.8.0-beta.1' # -- supported-kubernetes-version: 1.21 supported-helm-version: 3.10.0 diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index fa9be0dd40..e6dc477588 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -3,13 +3,17 @@ ** xref:get-started:whats-new.adoc[] ** xref:get-started:intro-to-events.adoc[Introduction to Redpanda] ** xref:get-started:architecture.adoc[How Redpanda Works] +** xref:console:index.adoc[Introduction to Redpanda Console] ** xref:get-started:install-beta.adoc[Install Beta] -** xref:get-started:quick-start.adoc[Quickstart] +** xref:get-started:quickstarts.adoc[Quickstarts] +*** xref:get-started:quick-start.adoc[Redpanda Self-Managed] +*** xref:console:quickstart.adoc[Redpanda Console] ** xref:get-started:licensing/index.adoc[Redpanda Licensing] *** xref:get-started:licensing/overview.adoc[Editions and Enterprise Features] *** xref:get-started:licensing/add-license-redpanda/index.adoc[Add an Enterprise License] **** xref:get-started:licensing/add-license-redpanda/linux.adoc[Linux] **** xref:get-started:licensing/add-license-redpanda/kubernetes.adoc[Kubernetes] +**** xref:console:ui/add-license.adoc[Redpanda Console] *** xref:get-started:licensing/monitor-license-status.adoc[Monitor Enterprise Licenses] ** xref:get-started:rpk/index.adoc[Redpanda CLI] *** xref:get-started:intro-to-rpk.adoc[Introduction to rpk] @@ -40,6 +44,7 @@ *** xref:develop:data-transforms/deploy.adoc[Deploy] *** xref:develop:data-transforms/test.adoc[Test] *** xref:develop:data-transforms/monitor.adoc[Monitor] +*** xref:console:ui/data-transforms.adoc[Manage in Redpanda Console] *** xref:develop:data-transforms/upgrade.adoc[Upgrade] *** xref:develop:data-transforms/versioning-compatibility.adoc[Versioning and Compatibility] *** xref:develop:data-transforms/labs.adoc[Examples] @@ -129,9 +134,6 @@ **** xref:manage:kubernetes/monitoring/k-monitor-connectors.adoc[Connectors] *** xref:manage:kubernetes/k-rolling-restart.adoc[Rolling Restart] *** xref:manage:kubernetes/k-resilience-testing.adoc[Resilience Testing] -*** xref:manage:kubernetes/troubleshooting/index.adoc[Troubleshooting] -**** xref:manage:kubernetes/troubleshooting/k-troubleshoot.adoc[] -**** xref:manage:kubernetes/troubleshooting/k-diagnostics-bundle.adoc[Diagnostics Bundle] ** xref:manage:cluster-maintenance/index.adoc[Cluster Maintenance] *** xref:manage:cluster-maintenance/cluster-property-configuration.adoc[] *** xref:manage:cluster-maintenance/node-property-configuration.adoc[] @@ -146,7 +148,6 @@ *** xref:manage:cluster-maintenance/manage-throughput.adoc[Manage Throughput] *** xref:manage:cluster-maintenance/compaction-settings.adoc[Compaction Settings] *** xref:manage:cluster-maintenance/configure-availability.adoc[Configure Availability] -*** xref:manage:cluster-maintenance/cluster-diagnostics.adoc[Cluster Diagnostics] *** xref:manage:cluster-maintenance/partition-recovery.adoc[Forced Partition Recovery] *** xref:manage:cluster-maintenance/nodewise-partition-recovery.adoc[Node-wise Partition Recovery] ** xref:manage:security/index.adoc[Security] @@ -169,9 +170,8 @@ *** xref:manage:schema-reg/schema-reg-overview.adoc[] *** xref:manage:schema-reg/schema-reg-api.adoc[] *** xref:manage:schema-reg/schema-id-validation.adoc[] +*** xref:console:ui/schema-reg.adoc[Manage in Redpanda Console] ** xref:manage:console/index.adoc[Redpanda Console] -*** xref:console:index.adoc[Overview] -*** xref:console:quickstart.adoc[Quickstart] *** xref:console:config/index.adoc[Configuration] **** xref:console:config/configure-console.adoc[Configure Console] **** xref:console:config/enterprise-license.adoc[Add an Enterprise License] @@ -191,9 +191,6 @@ **** xref:console:config/deserialization.adoc[Deserialization] **** xref:console:config/kafka-connect.adoc[Kafka Connect] **** xref:console:config/topic-documentation.adoc[Topic Documentation] -*** xref:console:ui/add-license.adoc[Add an Enterprise License] -*** xref:console:ui/schema-reg.adoc[Schema Registry] -*** xref:console:ui/data-transforms.adoc[Data Transforms] *** xref:console:ui/programmable-push-filters.adoc[Filter Messages] *** xref:console:ui/record-deserialization.adoc[Deserialize Messages] *** xref:console:ui/edit-topic-configuration.adoc[Edit Topic Configuration] @@ -204,6 +201,17 @@ ** xref:manage:monitoring.adoc[] ** xref:manage:io-optimization.adoc[] ** xref:manage:raft-group-reconfiguration.adoc[Raft Group Reconfiguration] +* xref:troubleshoot:index.adoc[Troubleshoot] +** xref:troubleshoot:cluster-diagnostics/index.adoc[Cluster Diagnostics] +*** xref:troubleshoot:cluster-diagnostics/diagnose-issues.adoc[Linux] +*** xref:troubleshoot:cluster-diagnostics/k-diagnose-issues.adoc[Kubernetes] +** xref:troubleshoot:debug-bundle/index.adoc[Generate Debug Bundle] +*** xref:troubleshoot:debug-bundle/generate-debug-bundle.adoc[Linux] +*** xref:troubleshoot:debug-bundle/k-generate-debug-bundle.adoc[Kubernetes] +*** xref:console:ui/generate-bundle.adoc[Redpanda Console] +** xref:troubleshoot:errors-solutions/index.adoc[Resolve Errors] +*** xref:troubleshoot:errors-solutions/resolve-errors.adoc[Linux] +*** xref:troubleshoot:errors-solutions/k-resolve-errors.adoc[Kubernetes] * xref:reference:index.adoc[Reference] ** xref:reference:properties/index.adoc[] *** xref:reference:properties/broker-properties.adoc[] diff --git a/modules/console/images/broker-overview.png b/modules/console/images/broker-overview.png index 79281acacf..ad52e5b5c9 100644 Binary files a/modules/console/images/broker-overview.png and b/modules/console/images/broker-overview.png differ diff --git a/modules/console/images/js-filter.png b/modules/console/images/js-filter.png index 0af427dfad..23b627ac05 100644 Binary files a/modules/console/images/js-filter.png and b/modules/console/images/js-filter.png differ diff --git a/modules/console/images/license.png b/modules/console/images/license.png index 261ca723d8..da720acc75 100644 Binary files a/modules/console/images/license.png and b/modules/console/images/license.png differ diff --git a/modules/console/images/overview.png b/modules/console/images/overview.png index 740b83c397..96042370c5 100644 Binary files a/modules/console/images/overview.png and b/modules/console/images/overview.png differ diff --git a/modules/console/images/topic-documentation.png b/modules/console/images/topic-documentation.png index d2311749bd..513fe90a92 100644 Binary files a/modules/console/images/topic-documentation.png and b/modules/console/images/topic-documentation.png differ diff --git a/modules/console/images/topic.png b/modules/console/images/topic.png index 05a2e23f3b..a914096438 100644 Binary files a/modules/console/images/topic.png and b/modules/console/images/topic.png differ diff --git a/modules/console/images/user.png b/modules/console/images/user.png index 568a8c0922..65b1046cec 100644 Binary files a/modules/console/images/user.png and b/modules/console/images/user.png differ diff --git a/modules/console/pages/config/connect-to-redpanda.adoc b/modules/console/pages/config/connect-to-redpanda.adoc index 15b6832690..0e0ff7828d 100644 --- a/modules/console/pages/config/connect-to-redpanda.adoc +++ b/modules/console/pages/config/connect-to-redpanda.adoc @@ -66,7 +66,7 @@ kafka: [[admin]] == Configure access to the Redpanda Admin API -Configuring a connection to the Redpanda Admin API enables additional Redpanda-specific features in Redpanda Console, such as viewing the Redpanda version, managing data transforms, and SASL-SCRAM users. +Configuring a connection to the Redpanda Admin API enables additional Redpanda-specific features in Redpanda Console, such as viewing the Redpanda version, managing data transforms and SASL-SCRAM users, and generating debug bundles. [,yaml] ---- @@ -85,6 +85,8 @@ redpanda: # insecureSkipTlsVerify: false ---- +NOTE: Make sure to include the URLs of _all_ brokers in the `redpanda.adminApi.urls` array. + == Suggested reading - xref:console:config/deserialization.adoc[] diff --git a/modules/console/pages/config/security/authorization.adoc b/modules/console/pages/config/security/authorization.adoc index 7493c0f999..b8385851d8 100644 --- a/modules/console/pages/config/security/authorization.adoc +++ b/modules/console/pages/config/security/authorization.adoc @@ -47,6 +47,9 @@ It does not include permission to create/remove ACLs or to create or remove a se The `admin` role grants all permissions that come with the `editor` role and additionally includes: +* Access to the *Admin* page that includes: +** Details about all users and ACLs +** The ability to xref:console:ui/generate-bundle.adoc[generate debug bundles] * Managing all service account aspects (create/remove service accounts) * Managing all ACL aspects (create/remove ACLs) diff --git a/modules/console/pages/config/topic-documentation.adoc b/modules/console/pages/config/topic-documentation.adoc index 0e8eb21820..9359c8f5e3 100644 --- a/modules/console/pages/config/topic-documentation.adoc +++ b/modules/console/pages/config/topic-documentation.adoc @@ -4,7 +4,7 @@ You can embed your topic's documentation into the Redpanda Console user interface by providing access to a public or private Git repository that hosts your documentation files in Markdown format. -//image::topic-documentation.png[] +image::topic-documentation.png[] Redpanda Console clones the provided Git repository and stores all Markdown files it finds in memory. The *Documentation* tab in the frontend displays the content of the Markdown file that matches the name of the Kafka topic. diff --git a/modules/console/pages/index.adoc b/modules/console/pages/index.adoc index 7eac7749f0..630bcf18bb 100644 --- a/modules/console/pages/index.adoc +++ b/modules/console/pages/index.adoc @@ -1,4 +1,4 @@ -= Overview of Redpanda Console += Introduction to Redpanda Console :description: Learn about Redpanda Console: a web interface for managing and interacting with Redpanda clusters. :page-aliases: console:index/index.adoc, console:features/index.adoc, reference:console/index.adoc diff --git a/modules/console/pages/quickstart.adoc b/modules/console/pages/quickstart.adoc index 4cd6707702..7913c36421 100644 --- a/modules/console/pages/quickstart.adoc +++ b/modules/console/pages/quickstart.adoc @@ -77,7 +77,7 @@ include::console:attachment$transactions-schema.json[] ```bash docker compose up -d --wait ``` -// (step {"action":"runShell", "command": "docker pull docker.redpanda.com/redpandadata/redpanda:v${REDPANDA_VERSION:?Set a Redpanda version} && docker pull docker.redpanda.com/redpandadata/console:v${REDPANDA_CONSOLE_VERSION:?Set a Redpanda Console version} && docker pull docker.redpanda.com/redpandadata/connect:latest", "workingDirectory": "../test-resources", "timeout": 100000, "exitCodes": [0,1]}) +// (step {"action":"runShell", "command": "docker pull docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:-latest} && docker pull docker.redpanda.com/redpandadata/${CONSOLE_DOCKER_REPO:-console}:${REDPANDA_CONSOLE_VERSION:-latest} && docker pull docker.redpanda.com/redpandadata/connect:latest", "workingDirectory": "../test-resources", "timeout": 100000, "exitCodes": [0,1]}) // (step {"action":"runShell", "command": "docker compose up -d --wait", "workingDirectory": "../test-resources", "timeout": 50000, "exitCodes": [0,1]}) // (step {"action":"wait", "duration": 10000}) + @@ -141,15 +141,17 @@ Suppose you're asked to find all transactions related to the `.edu` domain. You // (step {"action":"find", "selector": "[data-testid='add-topic-filter-javascript']", "matchText": "JavaScript Filter", "click": true, "timeout": 10000}) . Give your filter a name such as 'Find .edu domains'. // (step {"action":"find", "selector": "[data-testid='add-javascript-filter-name']", "typeKeys": "Find .edu domains", "click": true, "timeout": 10000}) -// (step {"action":"saveScreenshot", "path": "js-filter.png", "directory": "../images", "overwrite": "byVariation"}) +// (step {"action":"saveScreenshot", "path": "js-filter.png", "directory": "../images", "overwrite": "byVariation", "maxVariation": 10}) + image::js-filter.png[] + . Replace the default JavaScript code with the following: + [,js] ---- return value.email.includes(".edu"); ---- + . Click *Save* to apply the filter. // (step {"action":"find", "selector": "[data-testid='add-javascript-filter-save']", "matchText": "Save", "click": true}) + @@ -290,6 +292,20 @@ See also: // (step {"action":"wait"}) // (step {"action":"saveScreenshot", "path": "license.png", "directory": "../images", "overwrite": "byVariation"}) +== Clean up + +If you don't want to continue experimenting with Redpanda, you can shut it down and delete the containers: + +```bash +docker compose down +``` + +To delete the volumes along with all your cluster data: + +```bash +docker compose down -v +``` + // (step {"action":"runShell", "command": "docker compose down -v", "workingDirectory": "../test-resources"}) // (test end) diff --git a/modules/console/pages/ui/add-license.adoc b/modules/console/pages/ui/add-license.adoc index 75cc383645..dc84f6e14c 100644 --- a/modules/console/pages/ui/add-license.adoc +++ b/modules/console/pages/ui/add-license.adoc @@ -6,24 +6,14 @@ You can add, update and check your xref:get-started:licensing/overview.adoc#cons == Prerequisites - You must have an Enterprise Edition license. https://www.redpanda.com/contact[Request a license^] if you don't have one already. -+ -If Redpanda Console has enterprise features enabled and it cannot find a valid license either locally or in the connected Redpanda cluster, it shuts down. - Redpanda Console must be xref:console:config/connect-to-redpanda.adoc[connected to a Redpanda cluster]. - Redpanda Console must be xref:console:config/connect-to-redpanda.adoc#admin[configured to connect to the Redpanda Admin API]. TIP: You can also xref:console:config/enterprise-license.adoc[configure Redpanda Console to load the license key from its local configuration]. -== Check the license status in Redpanda Console - -You can check the expiration date of a license on the **Cluster Overview** page in Redpanda Console, under the **Licensing** section. - -If the license is due to expire within 30 days, a warning banner is displayed on all pages of Redpanda Console. - -See also: xref:get-started:licensing/monitor-license-status.adoc[]. - -== Upload a new license +== Upload a license -When a new license is uploaded through Redpanda Console, it is replicated across the cluster and stored persistently in Redpanda's internal metadata, ensuring it is retained across restarts. +When a license is uploaded through Redpanda Console, it is replicated across the cluster and stored persistently in Redpanda's internal metadata, ensuring it is retained across restarts. [CAUTION] ==== @@ -51,6 +41,14 @@ When a new license is uploaded, enterprise features in Redpanda Self-Managed are After restarting Redpanda Console, enterprise features such as RBAC are unlocked. However, to enable and use these features, you must configure them. See xref:console:config/index.adoc[]. +== Check the license status in Redpanda Console + +You can check the expiration date of a license on the **Cluster Overview** page in Redpanda Console, under the **Licensing** section. + +If the license is due to expire within 30 days, a warning banner is displayed on all pages of Redpanda Console. + +See also: xref:get-started:licensing/monitor-license-status.adoc[]. + == Next steps xref:get-started:licensing/monitor-license-status.adoc[]. diff --git a/modules/console/pages/ui/generate-bundle.adoc b/modules/console/pages/ui/generate-bundle.adoc new file mode 100644 index 0000000000..d02a74ddd4 --- /dev/null +++ b/modules/console/pages/ui/generate-bundle.adoc @@ -0,0 +1,47 @@ += Manage Debug Bundles in Redpanda Console +:description: Learn how to generate, download, and delete debug bundles in Redpanda Console for comprehensive cluster diagnostics. + +[NOTE] +==== +include::shared:partial$enterprise-and-console.adoc[] +==== + +{description} + +== Prerequisites + +- Redpanda Console must be xref:console:config/connect-to-redpanda.adoc[connected to a Redpanda cluster] and xref:console:config/connect-to-redpanda.adoc#admin[configured to connect to the Redpanda Admin API]. +- Redpanda Console must be xref:console:config/security/authentication.adoc[configured with an authentication provider] and have at least one admin user. + +== Generate a debug bundle + +You can generate a debug bundle for all brokers in the cluster using Redpanda Console. After generating the bundle, download it onto your local computer for inspection. + +. Log in as an admin user. +. Click *Admin* in the sidebar. ++ +This option is visible only when you are logged in as an admin user. +. Go to *Debug bundle*. +. Click *Generate new*. +. Wait until the process is complete. +. Click *debug-bundle.zip* to download the bundle on your local computer. +. Unzip the file to inspect the contents. + +include::troubleshoot:partial$debug-bundle.adoc[tags=inspect] + +== Delete a debug bundle + +To generate a new debug bundle, you must delete the existing one. + +. Log in as an admin user. +. Click *Admin* in the sidebar. ++ +This option is visible only when you are logged in as an admin user. +. Go to *Debug bundle*. +. Click the trash icon next to *debug-bundle.zip* to delete the bundle. + +== Next steps + +- xref:troubleshoot:cluster-diagnostics/index.adoc[] +- xref:troubleshoot:errors-solutions/index.adoc[] + diff --git a/modules/console/test-resources/docker-compose.yml b/modules/console/test-resources/docker-compose.yml index 204699c358..9dcf0a0ff1 100644 --- a/modules/console/test-resources/docker-compose.yml +++ b/modules/console/test-resources/docker-compose.yml @@ -33,7 +33,7 @@ services: # Tells Seastar (the framework Redpanda uses under the hood) to use 1 core on the system. - --smp 1 - --default-log-level=info - image: docker.redpanda.com/redpandadata/redpanda:v${REDPANDA_VERSION:?Set a Redpanda version} + image: docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:-latest} container_name: redpanda-0 # Sets the username and password of the SCRAM superuser environment: @@ -68,7 +68,7 @@ services: - --smp 1 - --default-log-level=info - --seeds redpanda-0:33145 - image: docker.redpanda.com/redpandadata/redpanda:v${REDPANDA_VERSION:?Set a Redpanda version} + image: docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:-latest} container_name: redpanda-1 environment: RP_BOOTSTRAP_USER: "superuser:secretpassword" @@ -99,7 +99,7 @@ services: - --smp 1 - --default-log-level=info - --seeds redpanda-0:33145 - image: docker.redpanda.com/redpandadata/redpanda:v${REDPANDA_VERSION:?Set a Redpanda version} + image: docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:?Set a Redpanda version} container_name: redpanda-2 environment: RP_BOOTSTRAP_USER: "superuser:secretpassword" @@ -120,7 +120,7 @@ services: #################### console: container_name: redpanda-console - image: docker.redpanda.com/redpandadata/console:v${REDPANDA_CONSOLE_VERSION:?Set a Redpanda Console version} + image: docker.redpanda.com/redpandadata/${CONSOLE_DOCKER_REPO:-console}:${REDPANDA_CONSOLE_VERSION:-latest} networks: - redpanda_network entrypoint: /bin/sh @@ -235,7 +235,7 @@ services: - -X user=superuser - -X pass=secretpassword - -X registry.hosts=redpanda-0:8081 - image: docker.redpanda.com/redpandadata/redpanda:v${REDPANDA_VERSION:?Set a Redpanda version} + image: docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:-latest} # mount the local directory that contains your schema to the container. volumes: - ./transactions-schema.json:/etc/redpanda/transactions-schema.json diff --git a/modules/deploy/pages/deployment-option/self-hosted/kubernetes/k-production-deployment.adoc b/modules/deploy/pages/deployment-option/self-hosted/kubernetes/k-production-deployment.adoc index aeeb82b78c..77c32ad0fc 100644 --- a/modules/deploy/pages/deployment-option/self-hosted/kubernetes/k-production-deployment.adoc +++ b/modules/deploy/pages/deployment-option/self-hosted/kubernetes/k-production-deployment.adoc @@ -453,7 +453,7 @@ If you're using a private repository, always ensure your nodes have the necessar ---- image: repository: docker.redpanda.com/redpandadata/redpanda - tag: "v{full-version}" + tag: "{latest-redpanda-tag}" imagePullSecrets: [] ---- diff --git a/modules/deploy/partials/kubernetes/guides/troubleshoot.adoc b/modules/deploy/partials/kubernetes/guides/troubleshoot.adoc index e1013cbdfc..1f0aa789e4 100644 --- a/modules/deploy/partials/kubernetes/guides/troubleshoot.adoc +++ b/modules/deploy/partials/kubernetes/guides/troubleshoot.adoc @@ -2,6 +2,6 @@ Before troubleshooting your cluster, make sure that you have all the <>. -include::manage:kubernetes/troubleshooting/k-troubleshoot.adoc[tags=deployment,leveloffset=-1] +include::troubleshoot:partial$errors-and-solutions.adoc[tags=deployment,leveloffset=-1] For more troubleshooting steps, see xref:manage:kubernetes/troubleshooting/k-troubleshoot.adoc[Troubleshoot Redpanda in Kubernetes]. \ No newline at end of file diff --git a/modules/get-started/attachments/single-broker b/modules/get-started/attachments/single-broker new file mode 120000 index 0000000000..f41c920cf9 --- /dev/null +++ b/modules/get-started/attachments/single-broker @@ -0,0 +1 @@ +../test-resources/single-broker \ No newline at end of file diff --git a/modules/get-started/attachments/three-brokers b/modules/get-started/attachments/three-brokers new file mode 120000 index 0000000000..aac706a552 --- /dev/null +++ b/modules/get-started/attachments/three-brokers @@ -0,0 +1 @@ +../test-resources/three-brokers \ No newline at end of file diff --git a/modules/get-started/pages/install-beta.adoc b/modules/get-started/pages/install-beta.adoc index 07f22dd71b..4cb70201b6 100644 --- a/modules/get-started/pages/install-beta.adoc +++ b/modules/get-started/pages/install-beta.adoc @@ -2,7 +2,7 @@ :description: Learn how to install the beta version. :publish-only-during-beta: true -Redpanda beta versions provide users the opportunity to test and share feedback on new features before they're finalized in general availability. Beta versions, like `v{redpanda-beta-version}`, are published to `redpanda-unstable` as release candidate (RC) builds. RC builds are not recommended for production use. +Redpanda beta versions provide users the opportunity to test and share feedback on new features before they're finalized in general availability. Beta versions, like `{redpanda-beta-tag}`, are published to `redpanda-unstable` as release candidate (RC) builds. RC builds are not recommended for production use. To install the beta version, select your environment. @@ -16,7 +16,7 @@ Docker:: + [source,bash,subs="attributes+"] ---- -docker pull docker.redpanda.com/redpandadata/redpanda-unstable:v{redpanda-beta-version} +docker pull docker.redpanda.com/redpandadata/redpanda-unstable:{redpanda-beta-tag} ---- . Create a Docker Compose file with the beta version: @@ -59,7 +59,7 @@ services: - --mode dev-container # enable logs for debugging. - --default-log-level=debug - image: docker.redpanda.com/redpandadata/redpanda-unstable:v{redpanda-beta-version} + image: docker.redpanda.com/redpandadata/redpanda-unstable:{redpanda-beta-tag} container_name: redpanda-0 volumes: - redpanda-0:/var/lib/redpanda/data @@ -72,7 +72,7 @@ services: - 19644:9644 console: container_name: redpanda-console - image: docker.redpanda.com/redpandadata/console:v{latest-console-version} + image: docker.redpanda.com/redpandadata/console:{latest-console-tag} networks: - redpanda_network entrypoint: /bin/sh @@ -158,7 +158,7 @@ Install Redpanda with Helm from the RC build in https://hub.docker.com/r/redpand helm repo add redpanda https://charts.redpanda.com helm install redpanda redpanda/redpanda \ --namespace \ - --create-namespace --set image.repository=docker.redpanda.com/redpandadata/redpanda-unstable --set image.tag=v{redpanda-beta-version} + --create-namespace --set image.repository=docker.redpanda.com/redpandadata/redpanda-unstable --set image.tag={redpanda-beta-tag} ---- -- diff --git a/modules/get-started/pages/licensing/overview.adoc b/modules/get-started/pages/licensing/overview.adoc index 4dba69bd52..5aa89ea993 100644 --- a/modules/get-started/pages/licensing/overview.adoc +++ b/modules/get-started/pages/licensing/overview.adoc @@ -55,7 +55,7 @@ include::get-started:partial$licensing/enterprise-features.adoc[tag=connect] == How Redpanda Console handles licenses -If Redpanda Console cannot find a valid license either locally or in the connected Redpanda cluster, it shuts down. Redpanda Console tries to load a valid license for community or enterprise features at startup in the following order: +If Redpanda Console cannot find a valid license either locally or in the connected Redpanda cluster, it shuts down. Redpanda Console tries to load a valid license at startup in the following order: . From the local configuration file or environment variables. . From the connected Redpanda cluster (if available). diff --git a/modules/get-started/pages/quick-start.adoc b/modules/get-started/pages/quick-start.adoc index 0317142a73..e2e1c8684a 100644 --- a/modules/get-started/pages/quick-start.adoc +++ b/modules/get-started/pages/quick-start.adoc @@ -1,8 +1,12 @@ = Redpanda Self-Managed Quickstart :description: Learn how to quickly start working with a local Redpanda cluster. -:page-aliases: install-upgrade:index.adoc, install-upgrade:index/index.adoc, install-upgrade:start-streaming.adoc, quickstart:console-installation, quickstart:quick-start-docker.adoc, quickstart:quick-start-linux.adoc, quickstart:quick-start-macos.adoc, quickstart:quick-start-windows.adoc, getting-started:quick-start-docker.adoc, getting-started:quick-start-linux.adoc, getting-started:quick-start-windows.adoc, getting-started:quick-start-macos.adoc, console:installation.adoc, get-started:quick-start/quick-start-console.adoc, get-started:quick-start/quick-start-macos.adoc, get-started:quick-start/quick-start-linux.adoc, get-started:quick-start/quick-start-docker.adoc, get-started:quickstarts/index.adoc +:page-aliases: install-upgrade:index.adoc, install-upgrade:index/index.adoc, install-upgrade:start-streaming.adoc, quickstart:console-installation, quickstart:quick-start-docker.adoc, quickstart:quick-start-linux.adoc, quickstart:quick-start-macos.adoc, quickstart:quick-start-windows.adoc, getting-started:quick-start-docker.adoc, getting-started:quick-start-linux.adoc, getting-started:quick-start-windows.adoc, getting-started:quick-start-macos.adoc, console:installation.adoc, get-started:quick-start/quick-start-console.adoc, get-started:quick-start/quick-start-macos.adoc, get-started:quick-start/quick-start-linux.adoc, get-started:quick-start/quick-start-docker.adoc :page-categories: Deployment, Development, rpk :env-docker: true +// ========================AUTOMATED TESTS=================================== +// The comments in this file are used to run automated tests of all the documented steps. Tests are run on each pull request to the upstream repository using GitHub Actions. For more details about the testing tool we use, see https://doc-detective.com/. + +// (test start {"id": "quickstart", "description": "Redpanda Self-Managed quickstart"}) {description} @@ -46,7 +50,7 @@ For production environments where you need more resilience, a three-broker setup Single Broker:: + -- -. xref:redpanda-labs:docker-compose:attachment$single-broker/docker-compose.yml[Download] the following `docker-compose.yml` file on your local file system. +. xref:get-started:attachment$single-broker/docker-compose.yml[Download] the following `docker-compose.yml` file on your local file system. + .Reveal the YAML content [%collapsible] @@ -54,10 +58,14 @@ Single Broker:: .`docker-compose.yml` [,yaml,subs="attributes+"] ---- -include::redpanda-labs:docker-compose:attachment$single-broker/docker-compose.yml[] +include::get-started:attachment$single-broker/docker-compose.yml[] ---- ==== +// (step {"action":"runShell", "command": "docker pull docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:-latest} && docker pull docker.redpanda.com/redpandadata/${CONSOLE_DOCKER_REPO:-console}:${REDPANDA_CONSOLE_VERSION:-latest}", "workingDirectory": "../test-resources/single-broker", "timeout": 100000, "exitCodes": [0,1]}) +// (step {"action":"runShell", "command": "docker compose up -d --wait", "workingDirectory": "../test-resources/single-broker", "timeout": 50000, "exitCodes": [0,1]}) +// (step {"action":"wait", "duration": 10000}) + . Run the following in the directory where you saved the `docker-compose.yml` file: + ```bash @@ -77,7 +85,7 @@ Three Brokers:: + -- -. xref:redpanda-labs:docker-compose:attachment$three-brokers/docker-compose.yml[Download] the following `docker-compose.yml` file on your local file system. +. xref:get-started:attachment$three-brokers/docker-compose.yml[Download] the following `docker-compose.yml` file on your local file system. + .Reveal the YAML content [%collapsible] @@ -85,7 +93,7 @@ Three Brokers:: .`docker-compose.yml` [,yaml,subs="attributes+"] ---- -include::redpanda-labs:docker-compose:attachment$three-brokers/docker-compose.yml[] +include::get-started:attachment$three-brokers/docker-compose.yml[] ---- ==== @@ -125,6 +133,9 @@ To use `rpk` inside the Redpanda broker's Docker container: ```bash docker exec -it redpanda-0 rpk cluster info ``` +// (step {"action":"runShell", "command": "rpk profile create quickstart --from-profile rpk-profile.yaml", "workingDirectory": "../test-resources"}) +// (step {"action":"runShell", "command": "rpk cluster info", "workingDirectory": "../test-resources/single-broker"}) + . Create a topic called **chat-room**: + @@ -147,6 +158,7 @@ If you deployed three brokers, you can configure your topics with a replication docker exec -it redpanda-0 rpk topic create chat-room --replicas 3 ``` ==== +// (step {"action":"runShell", "command": "rpk topic create chat-room", "workingDirectory": "../test-resources/single-broker"}) . Produce a message to the topic: + @@ -166,6 +178,8 @@ Example output: ---- Produced to partition 0 at offset 0 with timestamp 1663282629789. ---- +// (step {"action":"runShell", "command": "echo 'Pandas are fabulous!' | rpk topic produce chat-room", "workingDirectory": "../test-resources/single-broker"}) + . Press kbd:[Ctrl + C] to finish producing messages to the topic. @@ -186,6 +200,8 @@ Your message is displayed along with its metadata: "offset": 0 } ``` +// (step {"action":"runShell", "command": "rpk topic consume chat-room --num 1", "output": "/Pandas are fabulous!/", "timeout": 10000}) + To test external connectivity using your local machine: @@ -295,6 +311,10 @@ To delete the volumes along with all your cluster data: docker compose down -v ``` +// (step {"action":"runShell", "command": "rpk profile delete quickstart"}) +// (step {"action":"runShell", "command": "docker compose down -v", "workingDirectory": "../test-resources/single-broker"}) +// (test end) + == Next steps - xref:redpanda-labs:ROOT:index.adoc[Try more examples in Redpanda Labs] diff --git a/modules/get-started/pages/quickstarts.adoc b/modules/get-started/pages/quickstarts.adoc new file mode 100644 index 0000000000..c4f0e22045 --- /dev/null +++ b/modules/get-started/pages/quickstarts.adoc @@ -0,0 +1,3 @@ += Redpanda Quickstarts +:description: Get started with Redpanda using these hands-on tutorials. Explore features that demonstrate how Redpanda can power your streaming applications. +:page-layout: index \ No newline at end of file diff --git a/modules/get-started/pages/whats-new.adoc b/modules/get-started/pages/whats-new.adoc index 69df5ca9c8..9c52336eeb 100644 --- a/modules/get-started/pages/whats-new.adoc +++ b/modules/get-started/pages/whats-new.adoc @@ -15,6 +15,10 @@ For topics with Tiered Storage enabled, you can unmount a topic to safely detach For a Redpanda cluster deployed across multiple availability zones (AZs), xref:develop:produce-data/leader-pinning.adoc[leader pinning] ensures that a topic's partition leaders are geographically closer to clients. Leader pinning can lower networking costs and help guarantee lower latency by routing produce and consume requests to brokers located in certain AZs. +== Debug bundles in Redpanda Console + +You can now xref:troubleshoot:debug-bundle/index.adoc[generate a debug bundle] in Redpanda Console for comprehensive diagnostics. A debug bundle can help debug and diagnose issues with a Redpanda cluster, a broker, or the machines on which the brokers are running. You can use this file to debug issues yourself, or you can send it to the Redpanda support team to help resolve your issue. + == Declarative user and ACL management in Kubernetes Redpanda now supports declarative management of users and access control lists (ACLs) using the new User custom resource with the Redpanda Operator. This feature allows you to: @@ -37,7 +41,7 @@ This release includes several updates to xref:get-started:licensing/overview.ado - *Unified license management in Redpanda Console*: You can now upload and apply a single license key for both Redpanda Console and the connected Redpanda cluster through the Redpanda Console UI. Any existing license key is overridden by the new one. -== New commands +== New commands The following `rpk` commands are new in this version: diff --git a/modules/get-started/test-resources/rpk-profile.yaml b/modules/get-started/test-resources/rpk-profile.yaml new file mode 100644 index 0000000000..47f52a08a5 --- /dev/null +++ b/modules/get-started/test-resources/rpk-profile.yaml @@ -0,0 +1,7 @@ +description: For use with the docker compose file +kafka_api: + brokers: + - 127.0.0.1:19092 +admin_api: + addresses: + - 127.0.0.1:19644 \ No newline at end of file diff --git a/modules/get-started/test-resources/single-broker/docker-compose.yml b/modules/get-started/test-resources/single-broker/docker-compose.yml new file mode 100644 index 0000000000..61cae308b8 --- /dev/null +++ b/modules/get-started/test-resources/single-broker/docker-compose.yml @@ -0,0 +1,74 @@ +name: redpanda-quickstart +networks: + redpanda_network: + driver: bridge +volumes: + redpanda-0: null + redpanda-1: null + redpanda-2: null +services: + ################## + # Redpanda Brokers # + ################## + redpanda-0: + command: + - redpanda + - start + - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:19092 + # Address the broker advertises to clients that connect to the Kafka API. + # Use the internal addresses to connect to the Redpanda brokers' + # from inside the same Docker network. + # Use the external addresses to connect to the Redpanda brokers' + # from outside the Docker network. + - --advertise-kafka-addr internal://redpanda-0:9092,external://localhost:19092 + - --pandaproxy-addr internal://0.0.0.0:8082,external://0.0.0.0:18082 + # Address the broker advertises to clients that connect to the HTTP Proxy. + - --advertise-pandaproxy-addr internal://redpanda-0:8082,external://localhost:18082 + - --schema-registry-addr internal://0.0.0.0:8081,external://0.0.0.0:18081 + # Redpanda brokers use the RPC API to communicate with each other internally. + - --rpc-addr redpanda-0:33145 + - --advertise-rpc-addr redpanda-0:33145 + # Mode dev-container uses well-known configuration properties for development in containers. + - --mode dev-container + # Tells Seastar (the framework Redpanda uses under the hood) to use 1 core on the system. + - --smp 1 + - --default-log-level=info + image: docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:-latest} + container_name: redpanda-0 + volumes: + - redpanda-0:/var/lib/redpanda/data + networks: + - redpanda_network + ports: + - 18081:18081 + - 18082:18082 + - 19092:19092 + - 19644:9644 + #################### + # Redpanda Console # + #################### + console: + container_name: redpanda-console + image: docker.redpanda.com/redpandadata/${CONSOLE_DOCKER_REPO:-console}:${REDPANDA_CONSOLE_VERSION:-latest} + networks: + - redpanda_network + entrypoint: /bin/sh + command: -c 'echo "$$CONSOLE_CONFIG_FILE" > /tmp/config.yml; /app/console -config.filepath=${CONFIG_FILEPATH:-/tmp/config.yml}' + volumes: + - ./config:/tmp/config/ + environment: + CONFIG_FILEPATH: ${CONFIG_FILEPATH:-/tmp/config.yml} + CONSOLE_CONFIG_FILE: | + kafka: + brokers: ["redpanda-0:9092"] + schemaRegistry: + enabled: true + urls: ["http://redpanda-0:8081"] + redpanda: + adminApi: + enabled: true + urls: ["http://redpanda-0:9644"] + ports: + - 8080:8080 + depends_on: + - redpanda-0 diff --git a/modules/get-started/test-resources/three-brokers/docker-compose.yml b/modules/get-started/test-resources/three-brokers/docker-compose.yml new file mode 100644 index 0000000000..3847ff27ae --- /dev/null +++ b/modules/get-started/test-resources/three-brokers/docker-compose.yml @@ -0,0 +1,132 @@ +name: redpanda-quickstart +networks: + redpanda_network: + driver: bridge +volumes: + redpanda-0: null + redpanda-1: null + redpanda-2: null +services: + ################## + # Redpanda Brokers # + ################## + redpanda-0: + command: + - redpanda + - start + - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:19092 + # Address the broker advertises to clients that connect to the Kafka API. + # Use the internal addresses to connect to the Redpanda brokers' + # from inside the same Docker network. + # Use the external addresses to connect to the Redpanda brokers' + # from outside the Docker network. + - --advertise-kafka-addr internal://redpanda-0:9092,external://localhost:19092 + - --pandaproxy-addr internal://0.0.0.0:8082,external://0.0.0.0:18082 + # Address the broker advertises to clients that connect to the HTTP Proxy. + - --advertise-pandaproxy-addr internal://redpanda-0:8082,external://localhost:18082 + - --schema-registry-addr internal://0.0.0.0:8081,external://0.0.0.0:18081 + # Redpanda brokers use the RPC API to communicate with each other internally. + - --rpc-addr redpanda-0:33145 + - --advertise-rpc-addr redpanda-0:33145 + # Mode dev-container uses well-known configuration properties for development in containers. + - --mode dev-container + # Tells Seastar (the framework Redpanda uses under the hood) to use 1 core on the system. + - --smp 1 + - --default-log-level=info + image: docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:-latest} + container_name: redpanda-0 + volumes: + - redpanda-0:/var/lib/redpanda/data + networks: + - redpanda_network + ports: + - 18081:18081 + - 18082:18082 + - 19092:19092 + - 19644:9644 + redpanda-1: + command: + - redpanda + - start + - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:29092 + - --advertise-kafka-addr internal://redpanda-1:9092,external://localhost:29092 + - --pandaproxy-addr internal://0.0.0.0:8082,external://0.0.0.0:28082 + - --advertise-pandaproxy-addr internal://redpanda-1:8082,external://localhost:28082 + - --schema-registry-addr internal://0.0.0.0:8081,external://0.0.0.0:28081 + - --rpc-addr redpanda-1:33145 + - --advertise-rpc-addr redpanda-1:33145 + - --mode dev-container + - --smp 1 + - --default-log-level=info + - --seeds redpanda-0:33145 + image: docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:-latest} + container_name: redpanda-1 + volumes: + - redpanda-1:/var/lib/redpanda/data + networks: + - redpanda_network + ports: + - 28081:28081 + - 28082:28082 + - 29092:29092 + - 29644:9644 + depends_on: + - redpanda-0 + redpanda-2: + command: + - redpanda + - start + - --kafka-addr internal://0.0.0.0:9092,external://0.0.0.0:39092 + - --advertise-kafka-addr internal://redpanda-2:9092,external://localhost:39092 + - --pandaproxy-addr internal://0.0.0.0:8082,external://0.0.0.0:38082 + - --advertise-pandaproxy-addr internal://redpanda-2:8082,external://localhost:38082 + - --schema-registry-addr internal://0.0.0.0:8081,external://0.0.0.0:38081 + - --rpc-addr redpanda-2:33145 + - --advertise-rpc-addr redpanda-2:33145 + - --mode dev-container + - --smp 1 + - --default-log-level=info + - --seeds redpanda-0:33145 + image: docker.redpanda.com/redpandadata/${REDPANDA_DOCKER_REPO:-redpanda}:${REDPANDA_VERSION:?Set a Redpanda version} + container_name: redpanda-2 + volumes: + - redpanda-2:/var/lib/redpanda/data + networks: + - redpanda_network + ports: + - 38081:38081 + - 38082:38082 + - 39092:39092 + - 39644:9644 + depends_on: + - redpanda-0 + #################### + # Redpanda Console # + #################### + console: + container_name: redpanda-console + image: docker.redpanda.com/redpandadata/${CONSOLE_DOCKER_REPO:-console}:${REDPANDA_CONSOLE_VERSION:-latest} + networks: + - redpanda_network + entrypoint: /bin/sh + command: -c 'echo "$$CONSOLE_CONFIG_FILE" > /tmp/config.yml; /app/console -config.filepath=${CONFIG_FILEPATH:-/tmp/config.yml}' + volumes: + - ./config:/tmp/config/ + environment: + CONFIG_FILEPATH: ${CONFIG_FILEPATH:-/tmp/config.yml} + CONSOLE_CONFIG_FILE: | + kafka: + brokers: ["redpanda-0:9092", "redpanda-1:9092", "redpanda-2:9092"] + schemaRegistry: + enabled: true + urls: ["http://redpanda-0:8081", "http://redpanda-1:8081", "http://redpanda-2:8081"] + redpanda: + adminApi: + enabled: true + urls: ["http://redpanda-0:9644", "http://redpanda-1:9644", "http://redpanda-2:9644"] + ports: + - 8080:8080 + depends_on: + - redpanda-0 + - redpanda-1 + - redpanda-2 diff --git a/modules/manage/pages/cluster-maintenance/cluster-diagnostics.adoc b/modules/manage/pages/cluster-maintenance/cluster-diagnostics.adoc deleted file mode 100644 index 45b76d81c9..0000000000 --- a/modules/manage/pages/cluster-maintenance/cluster-diagnostics.adoc +++ /dev/null @@ -1,106 +0,0 @@ -= Cluster Diagnostics -:description: Use tools and tests to help diagnose and debug a Redpanda cluster. -:page-categories: Management, Troubleshooting - -This topic provides guides for using tools and tests to help diagnose and debug a Redpanda cluster. - -[[self-test]] -== Disk and network self-test benchmarks - -When anomalous behavior arises in a cluster and you're trying to figure out whether it's caused by faulty hardware (disks, NICs) of a cluster's machines, run xref:reference:rpk/rpk-cluster/rpk-cluster-self-test.adoc[rpk cluster self-test] (self-test) to characterize their performance and compare it with their expected, vendor-specified performance. - -Self-test runs a set of benchmarks to determine the maximum performance of a machine's disks and network connections. For disks, it runs throughput and latency tests by performing concurrent sequential operations. For networks, it selects unique pairs of Redpanda nodes as client/server pairs, then it runs throughput tests between them. Self-test runs each benchmark for a configurable duration, and it returns IOPS, throughput, and latency metrics. - -== Cloud storage tests - -If you use xref:manage:tiered-storage.adoc[Tiered Storage], run self-test to verify that you have configured your cloud storage accounts correctly. - -Self-test performs the following tests to validate cloud storage configuration: - -include::reference:partial$rpk-self-test-cloud-tests.adoc[] - -See the xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-start.adoc[`rpk cluster self-test start`] reference for cloud storage test details. - -== Self-test command examples - -=== Start self-test - -To begin using self-test, run the `self-test start` command. - ----- -rpk cluster self-test start ----- - -For command help, run `rpk cluster self-test start -h`. For additional command flags, see the xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-start.adoc[rpk cluster self-test start] reference. - -Before it starts, `self-test start` asks for your confirmation to run its potentially large workload. - -Example start output: - -[.no-copy] ----- -? Redpanda self-test will run benchmarks of disk and network hardware that will consume significant system resources. Do not start self-test if large workloads are already running on the system. (Y/n) -Redpanda self-test has started, test identifier: "031be460-246b-46af-98f2-5fc16f03aed3", To check the status run: -rpk cluster self-test status ----- - -The `self-test start` command returns immediately, and self-test runs its benchmarks asynchronously. - -=== Check self-test status - -To check on the status of self-test, run the `self-test status` command. - -[,bash] ----- -rpk cluster self-test status ----- - -For command help, run `rpk cluster self-test status -h`. For additional command flags, see the xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[rpk cluster self-test status] reference. - -If benchmarks are currently running, `self-test status` returns a test-in-progress message. - -Example status output: - -[.no-copy] ----- -$ rpk cluster self-test status -Nodes [0 1 2] are still running jobs ----- - -[TIP] -==== -To automate checking the status of self-test, the `status` command can output its results in JSON format by using the `--format=json` option: - -[,bash] ----- -rpk cluster self-test status --format=json ----- - -==== - -If benchmarks have completed, `self-test status` returns their results. - -include::reference:partial$rpk-self-test-descriptions.adoc[] - -.Example status output: test results -include::reference:partial$rpk-self-test-status-output.adoc[] - -=== Stop self-test - -To stop a running self-test, run the `self-test stop` command. - ----- -rpk cluster self-test stop ----- - -Example stop output: - -[.no-copy] ----- -$ rpk cluster self-test stop -All self-test jobs have been stopped ----- - -For command help, run `rpk cluster self-test stop -h`. For additional command flags, see the xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc[rpk cluster self-test stop] reference. - -For more details about self-test, including command flags, see xref:reference:rpk/rpk-cluster/rpk-cluster-self-test.adoc[rpk cluster self-test]. diff --git a/modules/manage/pages/kubernetes/security/authentication/k-authentication.adoc b/modules/manage/pages/kubernetes/security/authentication/k-authentication.adoc index 56df29cc28..1891906b50 100644 --- a/modules/manage/pages/kubernetes/security/authentication/k-authentication.adoc +++ b/modules/manage/pages/kubernetes/security/authentication/k-authentication.adoc @@ -12,7 +12,7 @@ include::manage:partial$authentication.adoc[] This section lists error messages and provides ways to diagnose and solve issues. For more troubleshooting steps, see xref:manage:kubernetes/troubleshooting/k-troubleshoot.adoc[Troubleshoot Redpanda in Kubernetes]. -include::manage:kubernetes/troubleshooting/k-troubleshoot.adoc[tags=sasl] +include::troubleshoot:partial$errors-and-solutions.adoc[tags=sasl] == Next steps diff --git a/modules/manage/pages/kubernetes/security/tls/k-cert-manager.adoc b/modules/manage/pages/kubernetes/security/tls/k-cert-manager.adoc index e962e10b59..263c97b8dd 100644 --- a/modules/manage/pages/kubernetes/security/tls/k-cert-manager.adoc +++ b/modules/manage/pages/kubernetes/security/tls/k-cert-manager.adoc @@ -426,7 +426,7 @@ include::manage:partial$kubernetes/disable-tls.adoc[leveloffset=+1] Here are some common troubleshooting scenarios and their solutions. For more troubleshooting steps, see xref:manage:kubernetes/troubleshooting/k-troubleshoot.adoc[Troubleshoot Redpanda in Kubernetes]. -include::manage:kubernetes/troubleshooting/k-troubleshoot.adoc[tags=tls;networking] +include::troubleshoot:partial$errors-and-solutions.adoc[tags=tls;networking] == Next steps diff --git a/modules/manage/pages/kubernetes/security/tls/k-secrets.adoc b/modules/manage/pages/kubernetes/security/tls/k-secrets.adoc index ca16c3a999..d99ab3fc31 100644 --- a/modules/manage/pages/kubernetes/security/tls/k-secrets.adoc +++ b/modules/manage/pages/kubernetes/security/tls/k-secrets.adoc @@ -311,7 +311,7 @@ include::manage:partial$kubernetes/disable-tls.adoc[leveloffset=+1] Here are some common troubleshooting scenarios and their solutions. For more troubleshooting steps, see xref:manage:kubernetes/troubleshooting/k-troubleshoot.adoc[Troubleshoot Redpanda in Kubernetes]. -include::manage:kubernetes/troubleshooting/k-troubleshoot.adoc[tags=tls;networking] +include::troubleshoot:partial$errors-and-solutions.adoc[tags=tls;networking] == Next steps diff --git a/modules/manage/pages/kubernetes/troubleshooting/index.adoc b/modules/manage/pages/kubernetes/troubleshooting/index.adoc deleted file mode 100644 index ff6d3f9c0c..0000000000 --- a/modules/manage/pages/kubernetes/troubleshooting/index.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= Troubleshooting Redpanda in Kubernetes -:description: Learn how to diagnose and troubleshoot problems with Redpanda in Kubernetes. -:page-layout: index -:page-categories: Management, Troubleshooting -:env-kubernetes: true diff --git a/modules/manage/partials/troubleshooting.adoc b/modules/manage/partials/troubleshooting.adoc deleted file mode 100644 index 192e73f159..0000000000 --- a/modules/manage/partials/troubleshooting.adoc +++ /dev/null @@ -1,111 +0,0 @@ -//tag::deployment[] -=== A Redpanda Enterprise Edition license is required - -During a Redpanda upgrade, if enterprise features are enabled and a valid Enterprise Edition license is missing, Redpanda logs a warning and aborts the upgrade process on the affected broker. This issue prevents a successful upgrade. - -If you encounter this issue, follow these steps to recover: - -ifdef::env-kubernetes[] -. xref:upgrade:k-rolling-upgrade.adoc#roll-back[Roll back the affected broker to the original version]. -endif::[] -ifndef::env-kubernetes[] -. Roll back the affected broker to the original version. -endif::[] -. Do one of the following: -- xref:get-started:licensing/add-license-redpanda/index.adoc[Apply a valid Redpanda Enterprise Edition license] to the cluster. -- Disable enterprise features. -+ -If you do not have a valid license and want to proceed without using enterprise features, you can disable the enterprise features in your Redpanda configuration. - -. Retry the upgrade. - - -//end::deployment[] - -//tag::tls[] -=== Invalid large response size - -This error appears when your cluster is configured to use TLS, but you don't specify that you are connecting over TLS. - -[.no-copy] ----- -unable to request metadata: invalid large response size 352518912 > limit 104857600; the first three bytes received appear to be a tls alert record for TLS v1.2; is this a plaintext connection speaking to a tls endpoint? ----- - -If you're using rpk, ensure to add the `-X tls.enabled` flag, and any other necessary TLS flags such as the TLS certificate: - -[,bash] ----- -ifdef::env-kubernetes[kubectl exec -c redpanda --namespace -- \] -rpk cluster info -X tls.enabled=true ----- - -For all available flags, see the xref:reference:rpk/index.adoc[rpk command reference]. - -=== Malformed HTTP response - -This error appears when a cluster has TLS enabled, and you try to access the admin API without passing the required TLS parameters. - -[.no-copy] ----- -Retrying POST for error: Post "http://127.0.0.1:9644/v1/security/users": net/http: HTTP/1.x transport connection broken: malformed HTTP response "\x15\x03\x03\x00\x02\x02" ----- - -If you're using rpk, ensure to include the TLS flags. - -For all available flags, see the xref:reference:rpk/index.adoc[rpk command reference]. - -=== x509: certificate signed by unknown authority - -This error appears when the Certificate Authority (CA) that signed your certificates is not trusted by your system. - -Check the following: - -- Ensure you have installed the root CA certificate correctly on your local system. -- If using a self-signed certificate, ensure it is properly configured and included in your system's trust store. -- If you are using a certificate issued by a CA, ensure the issuing CA is included in your system's trust store. -ifdef::env-kubernetes[] -- If you are using cert-manager, ensure it is correctly configured and running properly. -endif::[] -- Check the validity of your certificates. They might have expired. - -=== x509: certificate is not valid for any names - -This error indicates that the certificate you are using is not valid for the specific domain or IP address you are trying to use it with. This error typically occurs when there is a mismatch between the certificate's Subject Alternative Name (SAN) or Common Name (CN) field and the name being used to access the broker. - -To fix this error, you may need to obtain a new certificate that is valid for the specific domain or IP address you are using. Ensure that the certificate's SAN or CN entry matches the name being used, and that the certificate is not expired or revoked. - -=== cannot validate certificate for 127.0.0.1 - -This error appears if you are using a CA certificate when you try to establish an internal connection using localhost. For example: - -``` -unable to request metadata: unable to dial: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs -``` - -To fix this error, you must either specify the URL with a public domain or use self-signed certificates: - -[,bash] ----- -ifdef::env-kubernetes[kubectl exec redpanda-0 -c redpanda --namespace -- \] -rpk cluster info \ --X brokers=: \ --X tls.enabled=true ----- - -//end::tls[] - -//tag::sasl[] -=== Is SASL missing? - -This error appears when you try to interact with a cluster that has SASL enabled without passing a user's credentials. - -[.no-copy] ----- -unable to request metadata: broker closed the connection immediately after a request was issued, which happens when SASL is required but not provided: is SASL missing? ----- - -If you're using rpk, ensure to specify the `-X user`, `-X pass`, and `-X sasl.mechanism` flags. - -For all available flags, see the xref:reference:rpk/index.adoc[rpk command reference]. -//end::sasl[] \ No newline at end of file diff --git a/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc b/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc index dbd4149300..4858fbdc70 100644 --- a/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc +++ b/modules/reference/pages/rpk/rpk-container/rpk-container-start.adoc @@ -73,7 +73,7 @@ rpk container start --admin-ports 9644,9645,9646 |-h, --help |- |Help for start. -|--image |string |An arbitrary container Redpanda image to use (default `redpandadata/redpanda:v{full-version}`). +|--image |string |An arbitrary container Redpanda image to use (default `redpandadata/redpanda:{latest-redpanda-tag}`). |--kafka-ports |strings |Kafka protocol ports to listen on; check help text for more information. diff --git a/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc b/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc index e631f33264..cb6d91316c 100644 --- a/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc +++ b/modules/reference/pages/rpk/rpk-debug/rpk-debug-bundle.adoc @@ -153,13 +153,15 @@ The files and directories in the diagnostics bundle differ depending on the envi Linux:: + -- -include::reference:partial$bundle-contents-linux.adoc[] +include::reference:partial$bundle-contents.adoc[] -- Kubernetes:: + -- -include::reference:partial$bundle-contents-k8s.adoc[] +:env-kubernetes: true + +include::reference:partial$bundle-contents.adoc[] -- ==== diff --git a/modules/reference/partials/bundle-contents-k8s.adoc b/modules/reference/partials/bundle-contents-k8s.adoc deleted file mode 100644 index 7d51c7379b..0000000000 --- a/modules/reference/partials/bundle-contents-k8s.adoc +++ /dev/null @@ -1,52 +0,0 @@ -NOTE: Redpanda collects some data from the Kubernetes API. -To communicate with the Kubernetes API, Redpanda requires a ClusterRole attached to the default ServiceAccount for the Pods. -The files and directories that are generated only when the ClusterRole exists are labeled *Requires ClusterRole*. - -|=== -| File or Directory | Description - -| `/admin` -| Cluster and broker configurations, cluster health data, and license key information. + -*Requires ClusterRole*. - -| `/controller` -| Binary-encoded replicated logs that contain the history of configuration changes as well as internal settings. + -Redpanda can replay the events that took place in the cluster to arrive at a similar state. - -| `data-dir.txt` -| Metadata for the Redpanda data directory of the broker on which the `rpk debug bundle` command was executed. - -| `du.txt` -| The disk usage of the data directory of the broker on which the `rpk debug bundle` command was executed, as output by the `du` command. - -| `/k8s` -| Kubernetes manifests for all resources in the given Kubernetes namespace. + -*Requires ClusterRole*. - -| `kafka.json` -| Kafka metadata, such as broker configuration, topic configuration, offsets, groups, and group commits. - -| `/logs` -| Logs of each Pod in the given Kubernetes namespace. + -If `--logs-since` is passed, only the logs within the given timeframe are included. + -*Requires ClusterRole*. - -| `/metrics` -| Prometheus metrics from both the `/metrics` endpoint and the `public_metrics` endpoint. + -One directory for each broker's metrics. + -*Requires ClusterRole*. - -| `ntp.txt` -| The NTP clock delta (using https://www.ntppool.org/en/[`ntppool`] as a reference) and round trip time of the broker on which the `rpk debug bundle` command was executed. - -| `/proc` -| CPU details of the broker on which the `rpk debug bundle` command was executed. + -The directory includes a `cpuinfo` file with CPU information such as processor model, core count, cache size, frequency, as well as an `interrupts` file that contains IRQ distribution across CPU cores. - -| `redpanda.yaml` -| The Redpanda configuration file of the broker on which the `rpk debug bundle` command was executed. + -Sensitive data is removed and replaced with `(REDACTED)`. - -| `resource-usage.json` -| Redpanda resource usage data, such as CPU usage and free memory available. -|=== diff --git a/modules/reference/partials/bundle-contents-linux.adoc b/modules/reference/partials/bundle-contents-linux.adoc deleted file mode 100644 index e7c450886f..0000000000 --- a/modules/reference/partials/bundle-contents-linux.adoc +++ /dev/null @@ -1,60 +0,0 @@ -NOTE: For some data, Redpanda requires the `rpk debug bundle` command to be run with root privileges. -The names of the files or directories that are generated only with root privileges are labeled *Requires root privileges*. - -[cols="1,1", options="header"] -|=== -|File or Directory |Description - -|`data-dir.txt` -|Metadata for the Redpanda data directory of the broker on which the `rpk debug bundle` command was executed. - -|`dig.txt` -|The DNS information, as output by the `dig` command, using the hosts in the `/etc/resolv.conf` file. - -|`dmidecode.txt` -|The contents of the DMI table (system management BIOS or SMBIOS). + -*Requires root privileges* - -|`du.txt` -|The disk usage of the data directory of the broker on which the `rpk debug bundle` command was executed, as output by the `du` command. - -|`ip.txt` -|Network configuration, as output by the `ip addr` command. - -|`kafka.json` -|Kafka metadata, such as broker configuration, topic configuration, offsets, groups, and group commits. - -|`lspci.txt` -|PCI buses and the devices connected to them. - -|`ntp.txt` -|The NTP clock delta (using https://www.ntppool.org/en/[`ntppool`] as a reference) and round trip time of the broker on which the `rpk debug bundle` command was executed. - -|`/proc` -|CPU details of the broker on which the `rpk debug bundle` command was executed. + -The directory includes a `cpuinfo` file with CPU information such as processor model, core count, cache size, and frequency, as well as an `interrupts` file that contains IRQ distribution across CPU cores. - -|`redpanda.log` -|The Redpanda logs written to journald. If `--logs-since` and/or `--logs-until` are passed, then only the logs within the given timeframe are included. - -|`prometheus-metrics.txt` -|The local broker's Prometheus metrics, fetched through its admin API. - -|`redpanda.yaml` -|The Redpanda configuration file of the broker on which the `rpk debug bundle` command was executed.
Sensitive data is removed and replaced with `(REDACTED)`. - -|`resource-usage.json` -|Redpanda resource usage data, such as CPU usage and free memory available. - -|`ss.txt` -|Data about active sockets, as output by the `ss` command. - -|`syslog.txt` -|The kernel logs ring buffer, as output by the `syslog` command. - -|`top.txt` -|Information about the running processes, as output by the `top` command. Check system processes. - -|`vmstat.txt` -|Virtual memory statistics, as output by the `vmstat` command. -|=== diff --git a/modules/reference/partials/bundle-contents.adoc b/modules/reference/partials/bundle-contents.adoc new file mode 100644 index 0000000000..591ca9c4e1 --- /dev/null +++ b/modules/reference/partials/bundle-contents.adoc @@ -0,0 +1,79 @@ +ifdef::env-kubernetes[] +NOTE: Redpanda collects some data from the Kubernetes API. +To communicate with the Kubernetes API, Redpanda requires a ClusterRole attached to the default ServiceAccount for the Pods. +The files and directories that are generated only when the ClusterRole exists are labeled *Requires ClusterRole*. +endif::[] + +|=== +| File or Directory | Description + +| `/admin` +| Cluster and broker configurations, cluster health data, and license key information. + +ifdef::env-kubernetes[] +*Requires ClusterRole*. +endif::[] + +| `/controller` +| Binary-encoded replicated logs that contain the history of configuration changes as well as internal settings. + +Redpanda can replay the events that took place in the cluster to arrive at a similar state. + +| `data-dir.txt` +| Metadata for the Redpanda data directory of the broker on which the `rpk debug bundle` command was executed. + +ifdef::env-kubernetes[] +| `/k8s` +| Kubernetes manifests for all resources in the given Kubernetes namespace. + +*Requires ClusterRole*. +endif::[] + +| `kafka.json` +| Kafka metadata, such as broker configuration, topic configuration, offsets, groups, and group commits. + +ifndef::env-kubernetes[] +| `redpanda.log` +|Redpanda logs for the broker. + +If `--logs-since` is passed, only the logs within the given timeframe are included. + +endif::[] + +ifdef::env-kubernetes[] +| `/logs` +|Logs from the Pods that run Redpanda in the given Kubernetes namespace. + +If `--logs-since` is passed, only the logs within the given timeframe are included. + +*Requires ClusterRole*. +endif::[] + +| `/metrics` +| Prometheus metrics from both the `/metrics` endpoint and the `public_metrics` endpoint. + +ifdef::env-kubernetes[] +*Requires ClusterRole*. +endif::[] + +| `/proc` +| CPU details of the broker on which the `rpk debug bundle` command was executed. + +The directory includes a `cpuinfo` file with CPU information such as processor model, core count, cache size, frequency, as well as an `interrupts` file that contains IRQ distribution across CPU cores. + +| `redpanda.yaml` +| The Redpanda configuration file of the broker on which the `rpk debug bundle` command was executed. + +Sensitive data is removed and replaced with `(REDACTED)`. + +| `resource-usage.json` +| Redpanda resource usage data, such as CPU usage and free memory available. + +| `/utils` +a| Data from the node on which the broker is running. This directory includes: + +- `du.txt`: The disk usage of the data directory of the broker on which the `rpk debug bundle` command was executed, as output by the `du` command. +- `ntp.txt`: The NTP clock delta (using https://www.ntppool.org/en/[`ntppool`] as a reference) and round trip time of the broker on which the `rpk debug bundle` command was executed. +- `uname.txt`: System information, such as the kernel version, hostname, and architecture, as output by the `uname` command. +ifndef::env-kubernetes[] +- `dig.txt`: The DNS resolution information for the node, as output by the `dig` command. +- `dmidecode.txt`: System hardware information from the node, as output by the the `dmidecode` command. *Requires root privileges*. +- `free.txt`: The amount of free and used memory on the node, as output by the `free` command. +- `ip.txt`: Network interface information, including IP addresses and network configuration, as output by the `ip` command. +- `lspci.txt`: Information about PCI devices on the node, as output by the `lspci` command. +- `ss.txt`: Active socket connections, as output by the `ss` command, showing network connections, listening ports, and more. +- `sysctl.txt`: Kernel parameters of the system, as output by the `sysctl` command. +- `top.txt`: The top processes by CPU and memory usage, as output by the `top` command. +- `vmstat.txt`: Virtual memory statistics, including CPU usage, memory, and IO operations, as output by the `vmstat` command. +endif::[] +|=== diff --git a/modules/shared/partials/enterprise-and-console.adoc b/modules/shared/partials/enterprise-and-console.adoc index 06c96248c7..f1698b5e94 100644 --- a/modules/shared/partials/enterprise-and-console.adoc +++ b/modules/shared/partials/enterprise-and-console.adoc @@ -1 +1,3 @@ -This section pertains to Redpanda Console in a self-managed deployment, and this feature requires an xref:get-started:licenses.adoc[Enterprise license]. To upgrade, contact https://redpanda.com/try-redpanda?section=enterprise-trial[Redpanda sales^]. \ No newline at end of file +This section pertains to Redpanda Console in a self-managed deployment, and this feature requires an xref:get-started:licenses.adoc[Enterprise license]. To upgrade, contact https://redpanda.com/try-redpanda?section=enterprise-trial[Redpanda sales^]. + +If Redpanda Console has enterprise features enabled and it cannot find a valid license either in its xref:console:config/enterprise-license.adoc[local configuration] or in the xref:get-started:licensing/add-license-redpanda/index.adoc[connected Redpanda cluster], it shuts down. \ No newline at end of file diff --git a/modules/troubleshoot/pages/cluster-diagnostics/diagnose-issues.adoc b/modules/troubleshoot/pages/cluster-diagnostics/diagnose-issues.adoc new file mode 100644 index 0000000000..afa5e0e8fa --- /dev/null +++ b/modules/troubleshoot/pages/cluster-diagnostics/diagnose-issues.adoc @@ -0,0 +1,7 @@ += Run Cluster Diagnostics in Linux +:description: Use this guide to diagnose and troubleshoot issues in a Redpanda cluster running in Linux. +:page-aliases: manage:cluster-maintenance/cluster-diagnostics.adoc + +{description} + +include::troubleshoot:partial$cluster-diagnostics.adoc[] \ No newline at end of file diff --git a/modules/troubleshoot/pages/cluster-diagnostics/index.adoc b/modules/troubleshoot/pages/cluster-diagnostics/index.adoc new file mode 100644 index 0000000000..9ac521e650 --- /dev/null +++ b/modules/troubleshoot/pages/cluster-diagnostics/index.adoc @@ -0,0 +1,5 @@ += Cluster Diagnostics +:description: Discover tools and tests to diagnose issues in Redpanda clusters across multiple environments. +:page-layout: index + +{description} \ No newline at end of file diff --git a/modules/troubleshoot/pages/cluster-diagnostics/k-diagnose-issues.adoc b/modules/troubleshoot/pages/cluster-diagnostics/k-diagnose-issues.adoc new file mode 100644 index 0000000000..2368451009 --- /dev/null +++ b/modules/troubleshoot/pages/cluster-diagnostics/k-diagnose-issues.adoc @@ -0,0 +1,7 @@ += Run Cluster Diagnostics in Kubernetes +:env-kubernetes: true +:description: Use this guide to diagnose and troubleshoot issues in a Redpanda cluster running in Kubernetes. + +{description} + +include::troubleshoot:partial$cluster-diagnostics.adoc[] \ No newline at end of file diff --git a/modules/troubleshoot/pages/debug-bundle/generate-debug-bundle.adoc b/modules/troubleshoot/pages/debug-bundle/generate-debug-bundle.adoc new file mode 100644 index 0000000000..287804f5d1 --- /dev/null +++ b/modules/troubleshoot/pages/debug-bundle/generate-debug-bundle.adoc @@ -0,0 +1,7 @@ += Generate a Debug Bundle in Linux +:page-categories: Management, Troubleshooting +:description: pass:q[Use `rpk` or Redpanda Console to generate a debug bundle to diagnose issues yourself, or send it to the Redpanda support team to help resolve your issue.] + +{description} + +include::troubleshoot:partial$debug-bundle.adoc[] \ No newline at end of file diff --git a/modules/troubleshoot/pages/debug-bundle/index.adoc b/modules/troubleshoot/pages/debug-bundle/index.adoc new file mode 100644 index 0000000000..5ea32ada34 --- /dev/null +++ b/modules/troubleshoot/pages/debug-bundle/index.adoc @@ -0,0 +1,5 @@ += Generate a Debug Bundle +:description: Generate a ZIP file with data that can help debug and diagnose issues with a Redpanda cluster, a broker, or the machines on which the brokers are running. +:page-layout: index + +{description} \ No newline at end of file diff --git a/modules/troubleshoot/pages/debug-bundle/k-generate-debug-bundle.adoc b/modules/troubleshoot/pages/debug-bundle/k-generate-debug-bundle.adoc new file mode 100644 index 0000000000..7023eaa25d --- /dev/null +++ b/modules/troubleshoot/pages/debug-bundle/k-generate-debug-bundle.adoc @@ -0,0 +1,9 @@ += Generate a Debug Bundle in Kubernetes +:page-aliases: manage:kubernetes/troubleshooting/diagnostics-bundle.adoc, manage:kubernetes/troubleshooting/k-diagnostics-bundle.adoc +:page-categories: Management, Troubleshooting +:env-kubernetes: true +:description: pass:q[Use `rpk` or Redpanda Console to generate a debug bundle to diagnose issues yourself, or send it to the Redpanda support team to help resolve your issue.] + +{description} + +include::troubleshoot:partial$debug-bundle.adoc[] \ No newline at end of file diff --git a/modules/troubleshoot/pages/errors-solutions/index.adoc b/modules/troubleshoot/pages/errors-solutions/index.adoc new file mode 100644 index 0000000000..23d9603962 --- /dev/null +++ b/modules/troubleshoot/pages/errors-solutions/index.adoc @@ -0,0 +1,5 @@ += Error Messages and Solutions +:description: Find solutions to common Redpanda errors, including error messages, explanations, and troubleshooting steps for Linux and Kubernetes deployments. +:page-layout: index + +{description} diff --git a/modules/troubleshoot/pages/errors-solutions/k-resolve-errors.adoc b/modules/troubleshoot/pages/errors-solutions/k-resolve-errors.adoc new file mode 100644 index 0000000000..b78a03cfd0 --- /dev/null +++ b/modules/troubleshoot/pages/errors-solutions/k-resolve-errors.adoc @@ -0,0 +1,12 @@ += Resolve Errors in Kubernetes +:description: This section describes errors or issues you might encounter while deploying Redpanda in Kubernetes and explains how to troubleshoot them. +:page-categories: Management, Troubleshooting +:page-aliases: manage:kubernetes/troubleshooting/troubleshoot.adoc, manage:kubernetes/troubleshooting/k-troubleshoot.adoc +:page-categories: Management, Troubleshooting +:env-kubernetes: true +:include-categories: true + +{description} + +include::troubleshoot:partial$errors-and-solutions.adoc[] + diff --git a/modules/troubleshoot/pages/errors-solutions/resolve-errors.adoc b/modules/troubleshoot/pages/errors-solutions/resolve-errors.adoc new file mode 100644 index 0000000000..ef9793ff54 --- /dev/null +++ b/modules/troubleshoot/pages/errors-solutions/resolve-errors.adoc @@ -0,0 +1,8 @@ += Resolve Errors in Linux +:description: This section describes errors or issues you might encounter while deploying Redpanda in Linux and explains how to troubleshoot them. +:page-categories: Management, Troubleshooting +:include-categories: true + +{description} + +include::troubleshoot:partial$errors-and-solutions.adoc[] \ No newline at end of file diff --git a/modules/troubleshoot/pages/index.adoc b/modules/troubleshoot/pages/index.adoc new file mode 100644 index 0000000000..3a6d892d71 --- /dev/null +++ b/modules/troubleshoot/pages/index.adoc @@ -0,0 +1,7 @@ += Troubleshoot Redpanda +:description: Find advice on diagnosing issues and handling errors when using Redpanda. +:page-layout: index +:page-categories: Management, Troubleshooting +:page-aliases: manage:kubernetes/troubleshooting/index.adoc + +Use these guides to troubleshoot Redpanda. Navigate through cluster diagnostics for specific environments or see the list of error messages and solutions. diff --git a/modules/troubleshoot/partials/cluster-diagnostics.adoc b/modules/troubleshoot/partials/cluster-diagnostics.adoc new file mode 100644 index 0000000000..7c8f8bb818 --- /dev/null +++ b/modules/troubleshoot/partials/cluster-diagnostics.adoc @@ -0,0 +1,372 @@ +ifdef::env-kubernetes[] +:link-errors: troubleshoot:errors-solutions/k-resolve-errors.adoc +:link-bundle: troubleshoot:debug-bundle/k-generate-debug-bundle.adoc +endif::[] +ifndef::env-kubernetes[] +:link-errors: troubleshoot:errors-solutions/resolve-errors.adoc +:link-bundle: troubleshoot:debug-bundle/generate-debug-bundle.adoc +endif::[] + +ifdef::env-kubernetes[] +== Prerequisites + +Before troubleshooting Redpanda, ensure that Kubernetes isn't the cause of the issue. For information about debugging applications in a Kubernetes cluster, see the https://kubernetes.io/docs/tasks/debug/[Kubernetes documentation^]. +endif::[] + +== Collect all debugging data + +For a comprehensive diagnostic snapshot, generate a debug bundle that collects detailed data for cluster, broker, or node analysis. + +See xref:{link-bundle}[] for details on generating a debug bundle. + +ifdef::env-kubernetes[] +== View Helm chart configuration + +To check the overrides that were applied to your deployment: + +[,bash] +---- +helm get values --namespace +---- + +If you're using the Redpanda Operator, the chart name matches the name of your Redpanda resource. + +To check all the values that were set in the Redpanda Helm chart, including any overrides: + +[,bash] +---- +helm get values --namespace --all +---- + +== View recent events + +To understand the latest events that occurred in your Redpanda cluster's namespace, you can sort events by their creation timestamp: + +[,bash] +---- +kubectl get events --namespace --sort-by='.metadata.creationTimestamp' +---- + +== View Redpanda logs + +Logs are crucial for monitoring and troubleshooting your Redpanda clusters. Redpanda brokers output logs to STDOUT, making them accessible via `kubectl`. + +To access logs for a specific Pod: + +. List all Pods to find the names of those that are running Redpanda brokers: ++ +[source,bash] +---- +kubectl get pods --namespace +---- + +. View logs for a particular Pod by replacing `` with the name of your Pod: ++ +[source,bash] +---- +kubectl logs --namespace +---- ++ +[TIP] +==== +For a comprehensive overview, you can view aggregated logs from all Pods in the StatefulSet: + +[,bash] +---- +kubectl logs --namespace -l app.kubernetes.io/component=redpanda-statefulset +---- +==== + +=== Change the default log level + +To change the default log level for all Redpanda subsystems, use the `logging.logLevel` configuration. Valid values are `trace`, `debug`, `info`, `warn`, `error`. + +Changing the default log level to `debug` can provide more detailed logs for diagnostics. This logging level increases the volume of generated logs. + +NOTE: To set different log levels for individual subsystems, see <>. + +[tabs] +====== +Helm + Operator:: ++ +-- +Apply the new log level: + +.`redpanda-cluster.yaml` +[source,yaml] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: Redpanda +metadata: + name: redpanda +spec: + chartRef: {} + clusterSpec: + logging: + logLevel: debug +---- + +Then, apply this configuration: + +[source,bash] +---- +kubectl apply -f redpanda-cluster.yaml --namespace +---- +-- + +Helm:: ++ +-- +Choose between using a custom values file or setting values directly: +[tabs] +==== +--values:: ++ +Specify logging settings in `logging.yaml`, then upgrade: ++ +.`logging.yaml` +[source,yaml] +---- +logging: + logLevel: debug +---- ++ +[source,bash] +---- +helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ + --values logging.yaml --reuse-values +---- +--set:: ++ +Directly set the log level during upgrade: ++ +[source,bash] +---- +helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ + --set logging.logLevel=debug +---- +==== +-- +====== + +After applying these changes, verify the log level by <> for the Redpanda Pods. + +=== Override the default log level for Redpanda subsystems + +You can override the log levels for individual subsystems, such as `rpc` and `kafka`, for more detailed logging control. Overrides exist for the entire length of the running Redpanda process. + +TIP: To temporarily override the log level for individual subsystems, you can use the xref:reference:rpk/rpk-redpanda/rpk-redpanda-admin-config-log-level-set.adoc[`rpk redpanda admin config log-level set`] command. + +. List all available subsystem loggers: ++ +[source,bash] +---- +kubectl exec -it --namespace -c redpanda -- rpk redpanda start --help-loggers +---- + +. Set the log level for one or more subsystems. In this example, the `rpc` and `kafka` subsystem loggers are set to `debug`. ++ +[tabs] +====== +Helm + Operator:: ++ +-- +Apply the new log level: + +.`redpanda-cluster.yaml` +[source,yaml] +---- +apiVersion: cluster.redpanda.com/v1alpha2 +kind: Redpanda +metadata: + name: redpanda +spec: + chartRef: {} + clusterSpec: + statefulset: + additionalRedpandaCmdFlags: + - '--logger-log-level=rpc=debug:kafka=debug' +---- + +Then, apply this configuration: + +[source,bash] +---- +kubectl apply -f redpanda-cluster.yaml --namespace +---- +-- + +Helm:: ++ +-- +Choose between using a custom values file or setting values directly: +[tabs] +==== +--values:: ++ +Specify logging settings in `logging.yaml`, then upgrade: ++ +.`logging.yaml` +[source,yaml] +---- +statefulset: + additionalRedpandaCmdFlags: + - '--logger-log-level=rpc=debug:kafka=debug' +---- ++ +[source,bash] +---- +helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ + --values logging.yaml --reuse-values +---- +--set:: ++ +Directly set the log level during upgrade: ++ +[source,bash] +---- +helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ + --set statefulset.additionalRedpandaCmdFlags="{--logger-log-level=rpc=debug:kafka=debug}" +---- +==== +-- +====== + +Overriding the log levels for specific subsystems provides enhanced visibility into Redpanda's internal operations, facilitating better debugging and monitoring. + +== View Redpanda Operator logs + +To learn what's happening with the Redpanda Operator and the associated Redpanda resources, you can inspect a combination of Kubernetes events and the resource manifests. By monitoring these events and resources, you can troubleshoot any issues that arise during the lifecycle of a Redpanda deployment. + +[,bash] +---- +kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace +---- + +=== Inspect Helm releases + +The Redpanda Operator uses Flux to deploy the Redpanda Helm chart. By inspecting the `helmreleases.helm.toolkit.fluxcd.io` resource, you can get detailed information about the Helm installation process for your Redpanda resource: + +[,bash] +---- +kubectl get helmreleases.helm.toolkit.fluxcd.io -o yaml --namespace +---- + +To check the Redpanda resource: + +[,bash] +---- +kubectl get redpandas.cluster.redpanda.com -o yaml --namespace +---- + +In both the HelmRelease and the Redpanda resource, the condition section reveals the ongoing status of the Helm installation. These conditions provide information on the success, failure, or pending status of various operations. +endif::[] + +[[self-test]] +== Self-test benchmarks + +When anomalous behavior arises in a cluster, you can determine if it's caused by issues with hardware, such as disk drives or network interfaces (NICs) by running xref:reference:rpk/rpk-cluster/rpk-cluster-self-test.adoc[`rpk cluster self-test`] to assess their performance and compare it to vendor specifications. + +The `rpk cluster self-test` command runs a set of benchmarks to gauge the maximum performance of a machine's disks and network connections: + +* **Disk tests**: Measures throughput and latency by performing concurrent sequential operations. +* **Network tests**: Selects unique pairs of Redpanda brokers as client/server pairs and runs throughput tests between them. + +Each benchmark runs for a configurable duration and returns IOPS, throughput, and latency metrics. This helps you determine if hardware performance aligns with expected vendor specifications. + +=== Cloud storage tests + +You can also use the self-test command to confirm your cloud storage is configured correctly for xref:manage:tiered-storage.adoc[Tiered Storage]. + +Self-test performs the following checks to validate cloud storage configuration: + +include::reference:partial$rpk-self-test-cloud-tests.adoc[] + +For more information on cloud storage test details, see the xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-start.adoc[`rpk cluster self-test start`] reference. + +=== Start self-test + +To start using self-test, run the `self-test start` command. Only initiate `self-test start` when system resources are available, as this operation can be resource-intensive. + +[,bash] +---- +rpk cluster self-test start +---- + +For command help, run `rpk cluster self-test start -h`. For additional command flags, see the xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-start.adoc[rpk cluster self-test start] reference. + +Before `self-test start` begins, it requests your confirmation to run its potentially large workload. + +Example start output: + +[.no-copy] +---- +? Redpanda self-test will run benchmarks of disk and network hardware that will consume significant system resources. Do not start self-test if large workloads are already running on the system. (Y/n) +Redpanda self-test has started, test identifier: "031be460-246b-46af-98f2-5fc16f03aed3", To check the status run: +rpk cluster self-test status +---- + +The `self-test start` command returns immediately, and self-test runs its benchmarks asynchronously. + +=== Check self-test status + +To check the status of self-test, run the `self-test status` command. + +[,bash] +---- +rpk cluster self-test status +---- + +For command help, run `rpk cluster self-test status -h`. For additional command flags, see the xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-status.adoc[rpk cluster self-test status] reference. + +If benchmarks are currently running, `self-test status` returns a test-in-progress message. + +Example status output: + +[.no-copy] +---- +$ rpk cluster self-test status +Nodes [0 1 2] are still running jobs +---- + +[TIP] +==== +The `status` command can output results in JSON format for automated checks or script integration. Use the `--format=json` option: + +[,bash] +---- +rpk cluster self-test status --format=json +---- +==== + +If benchmarks have completed, `self-test status` returns their results. + +include::reference:partial$rpk-self-test-descriptions.adoc[] + +.Example status output: test results +include::reference:partial$rpk-self-test-status-output.adoc[] + +=== Stop self-test + +To stop a running self-test, run the `self-test stop` command. + +[,bash] +---- +rpk cluster self-test stop +---- + +Example stop output: + +[.no-copy] +---- +$ rpk cluster self-test stop +All self-test jobs have been stopped +---- + +For command help, run `rpk cluster self-test stop -h`. For additional command flags, see the xref:reference:rpk/rpk-cluster/rpk-cluster-self-test-stop.adoc[rpk cluster self-test stop] reference. + +For more details about self-test, including command flags, see xref:reference:rpk/rpk-cluster/rpk-cluster-self-test.adoc[rpk cluster self-test]. + +== Next steps + +Learn how to xref:{link-errors}[resolve common errors]. \ No newline at end of file diff --git a/modules/manage/pages/kubernetes/troubleshooting/k-diagnostics-bundle.adoc b/modules/troubleshoot/partials/debug-bundle.adoc similarity index 85% rename from modules/manage/pages/kubernetes/troubleshooting/k-diagnostics-bundle.adoc rename to modules/troubleshoot/partials/debug-bundle.adoc index cf9b40aee2..a9c4314143 100644 --- a/modules/manage/pages/kubernetes/troubleshooting/k-diagnostics-bundle.adoc +++ b/modules/troubleshoot/partials/debug-bundle.adoc @@ -1,20 +1,14 @@ -= Diagnostics Bundles in Kubernetes -:description: Use the diagnostics bundle to debug issues yourself, or you can send it to the Redpanda support team to help resolve your issue. -:tags: ["Kubernetes"] -:page-aliases: manage:kubernetes/troubleshooting/diagnostics-bundle.adoc -:page-categories: Management, Troubleshooting -:env-kubernetes: true - -A diagnostics bundle is a ZIP file with data that can help debug and diagnose issues with a Redpanda cluster, a broker, or the machines on which the brokers are running. You can use this file to debug issues yourself, or you can send it to the Redpanda support team to help resolve your issue. - +ifndef::env-kubernetes[] == Prerequisites -Most files in the diagnostics bundle are JSON files. To make it easier to read these files, this guide uses jq. To install jq, see the https://stedolan.github.io/jq/download/[jq downloads page^]. +You must have xref:get-started:rpk-install.adoc[`rpk` installed] on your host machine. +endif::[] -These examples use the default values in Helm chart. If you've customized the Helm chart, you may need to provide custom values and/or flags. +== Generate a debug bundle with `rpk` -== Generate a diagnostics bundle +To generate a debug bundle with `rpk`, you can run the xref:reference:rpk/rpk-debug/rpk-debug-bundle.adoc[`rpk debug bundle`] command on each broker in the cluster. +ifdef::env-kubernetes[] . Create a ClusterRole to allow Redpanda to collect information from the Kubernetes API: + [tabs] @@ -85,23 +79,37 @@ If you aren't using the Helm chart, you can create the ClusterRole manually: kubectl create clusterrolebinding redpanda --clusterrole=view --serviceaccount=redpanda:default ``` ==== +endif::[] -. Execute the xref:reference:rpk/rpk-debug/rpk-debug-bundle.adoc[`rpk debug bundle`] command inside a Pod container that's running a Redpanda broker. -+ -In this example, the command is executed on a Pod called `redpanda-0`. + +. Execute the xref:reference:rpk/rpk-debug/rpk-debug-bundle.adoc[`rpk debug bundle`] command on a broker: + -```bash -kubectl exec -it --namespace redpanda-0 -c redpanda -- rpk debug bundle -``` +[,bash] +---- +ifdef::env-kubernetes[] +kubectl exec -it --namespace redpanda-0 -c redpanda -- rpk debug bundle --namespace +endif::[] +ifndef::env-kubernetes[] +rpk debug bundle +endif::[] +---- + If you have an upload URL from the Redpanda support team, -provide it in the `--upload-url` flag to upload your diagnostics bundle to Redpanda. +provide it in the `--upload-url` flag to upload your debug bundle to Redpanda. + -```bash +[,bash] +---- +ifdef::env-kubernetes[] kubectl exec -it --namespace redpanda-0 -c redpanda -- rpk debug bundle \ --upload-url \ --namespace -``` +endif::[] +ifndef::env-kubernetes[] +rpk debug bundle \ + --upload-url +endif::[] + +---- + Example output: + @@ -112,45 +120,60 @@ Creating bundle file... Debug bundle saved to "/var/lib/redpanda/1675440652-bundle.zip" ---- -. On your host machine, make a directory in which to save the diagnostics bundle: + +. On your host machine, make a directory in which to save the debug bundle: + ```bash -mkdir diagnostics-bundle +mkdir debug-bundle ``` -. Copy the diagnostics bundle from the Pod to your host machine: +. Copy the debug bundle ZIP file to the `debug-bundle` directory on your host machine. +ifdef::env-kubernetes[] + Replace `` with the name of your ZIP file. + ```bash -kubectl cp redpanda/redpanda-0:/var/lib/redpanda/ diagnostics-bundle/ +kubectl cp /redpanda-0:/var/lib/redpanda/ debug-bundle/.zip ``` +endif::[] . Unzip the file on your host machine. + ```bash -cd diagnostics-bundle -unzip +cd debug-bundle +unzip .zip ``` -. Remove the diagnostics bundle from the Redpanda container: +. Remove the debug bundle from the Redpanda broker: + +[,bash] +---- +ifdef::env-kubernetes[] +kubectl exec redpanda-0 -c redpanda --namespace -- rm /var/lib/redpanda/.zip +endif::[] +ifndef::env-kubernetes[] +rm /var/lib/redpanda/.zip +endif::[] +---- + +When you've finished troubleshooting, remove the debug bundle from your host machine: + ```bash -kubectl exec redpanda-0 -c redpanda --namespace -- rm /var/lib/redpanda/ +rm -r debug-bundle ``` +For a description of the files and directories, see <>. -When you've finished troubleshooting, remove the diagnostics bundle from your host machine: +== Generate a debug bundle with Redpanda Console -```bash -rm -r diagnostics-bundle -``` +See xref:console:ui/generate-bundle.adoc[]. -For a description of the files and directories, see <>. +// tag::inspect[] +== Inspect the debug bundle -== Inspect the diagnostics bundle +After downloading the debug bundle files, you can inspect the contents to debug your cluster. This section provides some useful data points to check while troubleshooting. -This section provides some useful data points to check while troubleshooting. +Most files in the debug bundle are JSON files. To make it easier to read these files, this section uses jq. To install jq, see the https://stedolan.github.io/jq/download/[jq downloads page^]. === View the version of Redpanda on all brokers @@ -160,11 +183,11 @@ cat admin/brokers.json | jq '.[] | .version' Example output: -[,json,role=no-copy] +[,json,role=no-copy,subs=attributes+] ---- -"v23.1.1" -"v23.1.1" -"v23.1.1" +"{latest-redpanda-tag}" +"{latest-redpanda-tag}" +"{latest-redpanda-tag}" ---- === View the maintenance status of all brokers @@ -254,7 +277,7 @@ cat admin/cluster_config.json | jq ``` ==== -=== Check Enterprise license keys +=== Check Enterprise Edition license keys ```bash cat admin/license.json | jq @@ -282,7 +305,7 @@ cat admin/license.json | jq To check the size of the directories and look for anomalies: ```bash -cat du.txt +cat utils/du.txt ``` .Example output @@ -627,14 +650,21 @@ cat kafka.json | jq '.[1:]' === View the Redpanda logs +ifdef::env-kubernetes[] ```bash cat logs/redpanda-0.txt # logs/redpanda-1.txt logs/redpanda-2.txt ``` +endif::[] +ifndef::env-kubernetes[] +```bash +cat redpanda.log +``` +endif::[] === Check for clock drift ```bash -cat ntp.txt | jq +cat utils/ntp.txt | jq ``` Use the output to check for clock drift. For details about how NTP works, see the http://www.ntp.org/ntpfaq/NTP-s-algo.htm[NTP documentation^]. @@ -654,6 +684,7 @@ Use the output to check for clock drift. For details about how NTP works, see th ``` ==== +ifdef::env-kubernetes[] === View Kubernetes manifests ```bash @@ -678,11 +709,15 @@ k8s ``` ==== -== Contents of the diagnostics bundle +endif::[] + +// end::inspect[] + +== Contents of the debug bundle -The diagnostics bundle includes the following files and directories: +The debug bundle includes the following files and directories: -include::reference:partial$bundle-contents-k8s.adoc[] +include::reference:partial$bundle-contents.adoc[] include::shared:partial$suggested-reading.adoc[] diff --git a/modules/manage/pages/kubernetes/troubleshooting/k-troubleshoot.adoc b/modules/troubleshoot/partials/errors-and-solutions.adoc similarity index 68% rename from modules/manage/pages/kubernetes/troubleshooting/k-troubleshoot.adoc rename to modules/troubleshoot/partials/errors-and-solutions.adoc index 5fd9b21ec4..8bc74eb67b 100644 --- a/modules/manage/pages/kubernetes/troubleshooting/k-troubleshoot.adoc +++ b/modules/troubleshoot/partials/errors-and-solutions.adoc @@ -1,269 +1,12 @@ -= Troubleshoot Redpanda in Kubernetes -:description: Find advice on how to diagnose and troubleshoot issues while deploying Redpanda in Kubernetes. -:tags: ["Kubernetes"] -:page-aliases: manage:kubernetes/troubleshooting/troubleshoot.adoc -:page-categories: Management, Troubleshooting -:env-kubernetes: true +ifdef::env-kubernetes+include-categories[] +== Kubernetes-related issues -This topic provides guidance on how to diagnose and troubleshoot issues with Redpanda deployments in Kubernetes. - -== Prerequisites - -Before troubleshooting Redpanda, ensure that Kubernetes isn't the cause of the issue. For information about debugging applications in a Kubernetes cluster, see the https://kubernetes.io/docs/tasks/debug/[Kubernetes documentation^]. - -== Collect all debugging data - -If you're unsure of what is wrong, you can generate a diagnostics bundle that contains a wide range of data to help debug and diagnose a Redpanda cluster or the nodes on which the brokers are running. - -See xref:./k-diagnostics-bundle.adoc[Diagnostics Bundles in Kubernetes]. - -== View Helm chart configuration - -To check the overrides that were applied to your deployment: - -[,bash] ----- -helm get values --namespace ----- - -If you're using the Redpanda Operator, the chart name matches the name of your Redpanda resource. - -To check all the values that were set in the Redpanda Helm chart, including any overrides: - -[,bash] ----- -helm get values --namespace --all ----- - -== View recent events - -To understand the latest events that occurred in your Redpanda cluster's namespace, you can sort events by their creation timestamp: - -[,bash] ----- -kubectl get events --namespace --sort-by='.metadata.creationTimestamp' ----- - -== View Redpanda logs - -Logs are crucial for monitoring and troubleshooting your Redpanda clusters. Redpanda brokers output logs to STDOUT, making them accessible via `kubectl`. - -To access logs for a specific Pod: - -. List all Pods to find the names of those that are running Redpanda brokers: -+ -[source,bash] ----- -kubectl get pods --namespace ----- - -. View logs for a particular Pod by replacing `` with the name of your Pod: -+ -[source,bash] ----- -kubectl logs --namespace ----- -+ -[TIP] -==== -For a comprehensive overview, you can view aggregated logs from all Pods in the StatefulSet: - -[source,bash] ----- -kubectl logs --namespace -l app.kubernetes.io/component=redpanda-statefulset ----- -==== - -=== Change the default log level - -To change the default log level for all Redpanda subsystems, use the `logging.logLevel` configuration. Valid values are `trace`, `debug`, `info`, `warn`, `error`. - -Changing the default log level to `debug` can provide more detailed logs for diagnostics. This logging level increases the volume of generated logs. - -NOTE: To set different log levels for individual subsystems, see <>. - -[tabs] -====== -Helm + Operator:: -+ --- -Apply the new log level: - -.`redpanda-cluster.yaml` -[source,yaml] ----- -apiVersion: cluster.redpanda.com/v1alpha2 -kind: Redpanda -metadata: - name: redpanda -spec: - chartRef: {} - clusterSpec: - logging: - logLevel: debug ----- - -Then, apply this configuration: - -[source,bash] ----- -kubectl apply -f redpanda-cluster.yaml --namespace ----- --- - -Helm:: -+ --- -Choose between using a custom values file or setting values directly: -[tabs] -==== ---values:: -+ -Specify logging settings in `logging.yaml`, then upgrade: -+ -.`logging.yaml` -[source,yaml] ----- -logging: - logLevel: debug ----- -+ -[source,bash] ----- -helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ - --values logging.yaml --reuse-values ----- ---set:: -+ -Directly set the log level during upgrade: -+ -[source,bash] ----- -helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ - --set logging.logLevel=debug ----- -==== --- -====== - -After applying these changes, verify the log level by <> for the Redpanda Pods. - -=== Override the default log level for Redpanda subsystems - -You can override the log levels for individual subsystems, such as `rpc` and `kafka`, for more detailed logging control. Overrides exist for the entire length of the running Redpanda process. - -TIP: To temporarily override the log level for individual subsystems, you can use the xref:reference:rpk/rpk-redpanda/rpk-redpanda-admin-config-log-level-set.adoc[`rpk-redpanda-admin-config-log-level-set`] command. - -. List all available subsystem loggers: -+ -[source,bash] ----- -kubectl exec -it --namespace -c redpanda -- rpk redpanda start --help-loggers ----- - -. Set the log level for one or more subsystems. In this example, the `rpc` and `kafka` subsystem loggers are set to `debug`. -+ -[tabs] -====== -Helm + Operator:: -+ --- -Apply the new log level: - -.`redpanda-cluster.yaml` -[source,yaml] ----- -apiVersion: cluster.redpanda.com/v1alpha2 -kind: Redpanda -metadata: - name: redpanda -spec: - chartRef: {} - clusterSpec: - statefulset: - additionalRedpandaCmdFlags: - - '--logger-log-level=rpc=debug:kafka=debug' ----- - -Then, apply this configuration: - -[source,bash] ----- -kubectl apply -f redpanda-cluster.yaml --namespace ----- --- - -Helm:: -+ --- -Choose between using a custom values file or setting values directly: -[tabs] -==== ---values:: -+ -Specify logging settings in `logging.yaml`, then upgrade: -+ -.`logging.yaml` -[source,yaml] ----- -statefulset: - additionalRedpandaCmdFlags: - - '--logger-log-level=rpc=debug:kafka=debug' ----- -+ -[source,bash] ----- -helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ - --values logging.yaml --reuse-values ----- ---set:: -+ -Directly set the log level during upgrade: -+ -[source,bash] ----- -helm upgrade --install redpanda redpanda/redpanda --namespace --create-namespace \ - --set statefulset.additionalRedpandaCmdFlags="{--logger-log-level=rpc=debug:kafka=debug}" ----- -==== --- -====== - -Overriding the log levels for specific subsystems provides enhanced visibility into Redpanda's internal operations, facilitating better debugging and monitoring. - -== View Redpanda Operator logs - -To learn what's happening with the Redpanda Operator and the associated Redpanda resources, you can inspect a combination of Kubernetes events and the resource manifests. By monitoring these events and resources, you can troubleshoot any issues that arise during the lifecycle of a Redpanda deployment. - -[,bash] ----- -kubectl logs -l app.kubernetes.io/name=operator -c manager --namespace ----- - -=== Inspect Helm releases - -The Redpanda Operator uses Flux to deploy the Redpanda Helm chart. By inspecting the `helmreleases.helm.toolkit.fluxcd.io` resource, you can get detailed information about the Helm installation process for your Redpanda resource: - -[,bash] ----- -kubectl get helmreleases.helm.toolkit.fluxcd.io -o yaml --namespace ----- - -To check the Redpanda resource: - -[,bash] ----- -kubectl get redpandas.cluster.redpanda.com -o yaml --namespace ----- - -In both the HelmRelease and the Redpanda resource, the condition section reveals the ongoing status of the Helm installation. These conditions provide information on the success, failure, or pending status of various operations. - -== Troubleshoot known issues - -This section describes issues you might encounter while deploying Redpanda in Kubernetes and explains how to troubleshoot them. +This section addresses common issues that may occur when deploying Redpanda in a Kubernetes environment. +endif::[] //tag::deployment[] //tag::deployment-helm-release-not-ready[] +ifdef::env-kubernetes[] === HelmRelease is not ready If you are using the Redpanda Operator, you may see the following message while waiting for a Redpanda custom resource to be deployed: @@ -337,61 +80,6 @@ flux resume helmrelease --namespace ``` //end::deployment-retries-exhausted[] -//tag::crashloopbackoff[] -=== Crash loop backoffs - -If a broker crashes after startup, or gets stuck in a crash loop, it could produce progressively more stored state that uses additional disk space and takes more time for each restart to process. - -To prevent infinite crash loops, the Redpanda Helm chart sets the `crash_loop_limit` node property to 5. The crash loop limit is the number of consecutive crashes that can happen within one hour of each other. After Redpanda reaches this limit, it will not start until its internal consecutive crash counter is reset to zero. In Kubernetes, the Pod running Redpanda remains in a `CrashLoopBackoff` state until its internal consecutive crash counter is reset to zero. - -To troubleshoot a crash loop backoff: - -. Check the Redpanda logs from the most recent crashes: -+ -[,bash] ----- -kubectl logs --namespace ----- -+ -NOTE: Kubernetes retains logs only for the current and the previous instance of a container. This limitation makes it difficult to access logs from earlier crashes, which may contain vital clues about the root cause of the issue. Given these log retention limitations, setting up a centralized logging system is crucial. Systems such as https://grafana.com/docs/loki/latest/[Loki] or https://www.datadoghq.com/product/log-management/[Datadog] can capture and store logs from all containers, ensuring you have access to historical data. - -. Resolve the issue that led to the crash loop backoff. - -. Reset the crash counter to zero to allow Redpanda to restart. You can do any of the following to reset the counter: -+ -- Make changes to any of the following sections in the Redpanda Helm chart to trigger an update: -+ --- -* `config.node` -* `config.tunable` --- -+ -For example: -+ -```yaml -config: - node: - crash_loop_limit: -``` - -- Delete the `startup_log` file in the broker's data directory. -+ -[,bash] ----- -kubectl exec --namespace -- rm /var/lib/redpanda/data/startup_log ----- -+ -NOTE: It might be challenging to execute this command within a Pod that is in a `CrashLoopBackoff` state due to the limited time during which the Pod is available before it restarts. Wrapping the command in a loop might work. - -- Wait one hour since the last crash. The crash counter resets after one hour. - -To avoid future crash loop backoffs and manage the accumulation of small segments effectively: - -* xref:manage:kubernetes/monitoring/k-monitor-redpanda.adoc[Monitor] the size and number of segments regularly. -* Optimize your Redpanda configuration for segment management. -* Consider implementing xref:manage:kubernetes/storage/tiered-storage/k-tiered-storage.adoc[Tiered Storage] to manage data more efficiently. -//end::crashloopbackoff[] - //tag::deployment-pod-pending[] === StatefulSet never rolls out @@ -697,19 +385,104 @@ After clearing the `pending-rollback` state: * *Perform a rollback*: If you need to roll back to a previous release, use `helm rollback ` to revert to a specific, stable release version. //end::pending-rollback[] -include::manage:partial$troubleshooting.adoc[tags=deployment] -//end::deployment[] +endif::[] +ifdef::include-categories[] +== Deployment issues -//tag::tls[] -include::manage:partial$troubleshooting.adoc[tags=tls] +This section addresses common deployment issues encountered during Redpanda setup or upgrades. +endif::[] -=== Redpanda not applying TLS changes +//tag::crashloopbackoff[] +ifdef::env-kubernetes[] +=== Crash loop backoffs -include::manage:partial$kubernetes/tls-update-note.adoc[] +If a broker crashes after startup, or gets stuck in a crash loop, it could produce progressively more stored state that uses additional disk space and takes more time for each restart to process. + +To prevent infinite crash loops, the Redpanda Helm chart sets the `crash_loop_limit` node property to 5. The crash loop limit is the number of consecutive crashes that can happen within one hour of each other. After Redpanda reaches this limit, it will not start until its internal consecutive crash counter is reset to zero. In Kubernetes, the Pod running Redpanda remains in a `CrashLoopBackoff` state until its internal consecutive crash counter is reset to zero. + +To troubleshoot a crash loop backoff: + +. Check the Redpanda logs from the most recent crashes: ++ +[,bash] +---- +kubectl logs --namespace +---- ++ +NOTE: Kubernetes retains logs only for the current and the previous instance of a container. This limitation makes it difficult to access logs from earlier crashes, which may contain vital clues about the root cause of the issue. Given these log retention limitations, setting up a centralized logging system is crucial. Systems such as https://grafana.com/docs/loki/latest/[Loki] or https://www.datadoghq.com/product/log-management/[Datadog] can capture and store logs from all containers, ensuring you have access to historical data. + +. Resolve the issue that led to the crash loop backoff. + +. Reset the crash counter to zero to allow Redpanda to restart. You can do any of the following to reset the counter: ++ +- Make changes to any of the following sections in the Redpanda Helm chart to trigger an update: ++ +-- +* `config.node` +* `config.tunable` +-- ++ +For example: ++ +```yaml +config: + node: + crash_loop_limit: +``` + +- Delete the `startup_log` file in the broker's data directory. ++ +[,bash] +---- +kubectl exec --namespace -- rm /var/lib/redpanda/data/startup_log +---- ++ +NOTE: It might be challenging to execute this command within a Pod that is in a `CrashLoopBackoff` state due to the limited time during which the Pod is available before it restarts. Wrapping the command in a loop might work. + +- Wait one hour since the last crash. The crash counter resets after one hour. + +To avoid future crash loop backoffs and manage the accumulation of small segments effectively: + +* xref:manage:kubernetes/monitoring/k-monitor-redpanda.adoc[Monitor] the size and number of segments regularly. +* Optimize your Redpanda configuration for segment management. +* Consider implementing xref:manage:kubernetes/storage/tiered-storage/k-tiered-storage.adoc[Tiered Storage] to manage data more efficiently. + +endif::[] +//end::crashloopbackoff[] + +=== A Redpanda Enterprise Edition license is required + +During a Redpanda upgrade, if enterprise features are enabled and a valid Enterprise Edition license is missing, Redpanda logs a warning and aborts the upgrade process on the affected broker. This issue prevents a successful upgrade. + +If you encounter this issue, follow these steps to recover: + +ifdef::env-kubernetes[] +. xref:upgrade:k-rolling-upgrade.adoc#roll-back[Roll back the affected broker to the original version]. +endif::[] +ifndef::env-kubernetes[] +. Roll back the affected broker to the original version. +endif::[] +. Do one of the following: +- xref:get-started:licensing/add-license-redpanda/index.adoc[Apply a valid Redpanda Enterprise Edition license] to the cluster. +- Disable enterprise features. ++ +If you do not have a valid license and want to proceed without using enterprise features, you can disable the enterprise features in your Redpanda configuration. + +. Retry the upgrade. + +//end::deployment[] + +ifdef::include-categories[] +ifdef::env-kubernetes[] +== Networking issues + +This section provides insights into diagnosing network-related errors, such as connection timeouts, DNS misconfigurations, and network stability. +endif::[] +endif::[] -//end::tls[] // tag::networking[] +ifdef::env-kubernetes[] === I/O timeout This error appears when your worker nodes are unreachable through the given address. @@ -719,11 +492,105 @@ Check the following: * The address and port are correct. * Your DNS records point to addresses that resolve to your worker nodes. +endif::[] //end::networking[] -//tag::sasl[] -include::manage:partial$troubleshooting.adoc[tags=sasl] +ifdef::include-categories[] +== TLS issues + +This section covers common TLS errors, their causes, and solutions, including certificate issues and correct client configuration. + +endif::[] + +//tag::tls[] +ifdef::env-kubernetes[] +=== Redpanda not applying TLS changes + +include::manage:partial$kubernetes/tls-update-note.adoc[] + +endif::[] + +=== Invalid large response size + +This error appears when your cluster is configured to use TLS, but you don't specify that you are connecting over TLS. + +[.no-copy] +---- +unable to request metadata: invalid large response size 352518912 > limit 104857600; the first three bytes received appear to be a tls alert record for TLS v1.2; is this a plaintext connection speaking to a tls endpoint? +---- + +If you're using `rpk`, ensure to add the `-X tls.enabled` flag, and any other necessary TLS flags such as the TLS certificate: +[,bash] +---- +ifdef::env-kubernetes[kubectl exec -c redpanda --namespace -- \] +rpk cluster info -X tls.enabled=true +---- + +For all available flags, see the xref:reference:rpk/rpk-x-options.adoc[`rpk` options reference]. + +=== Malformed HTTP response + +This error appears when a cluster has TLS enabled, and you try to access the admin API without passing the required TLS parameters. + +[.no-copy] +---- +Retrying POST for error: Post "http://127.0.0.1:9644/v1/security/users": net/http: HTTP/1.x transport connection broken: malformed HTTP response "\x15\x03\x03\x00\x02\x02" +---- + +If you're using `rpk`, ensure to include the TLS flags. + +For all available flags, see the xref:reference:rpk/rpk-x-options.adoc[`rpk` options reference]. + +=== x509: certificate signed by unknown authority + +This error appears when the Certificate Authority (CA) that signed your certificates is not trusted by your system. + +Check the following: + +- Ensure you have installed the root CA certificate correctly on your local system. +- If using a self-signed certificate, ensure it is properly configured and included in your system's trust store. +- If you are using a certificate issued by a CA, ensure the issuing CA is included in your system's trust store. +ifdef::env-kubernetes[] +- If you are using cert-manager, ensure it is correctly configured and running properly. +endif::[] +- Check the validity of your certificates. They might have expired. + +=== x509: certificate is not valid for any names + +This error indicates that the certificate you are using is not valid for the specific domain or IP address you are trying to use it with. This error typically occurs when there is a mismatch between the certificate's Subject Alternative Name (SAN) or Common Name (CN) field and the name being used to access the broker. + +To fix this error, you may need to obtain a new certificate that is valid for the specific domain or IP address you are using. Ensure that the certificate's SAN or CN entry matches the name being used, and that the certificate is not expired or revoked. + +=== cannot validate certificate for 127.0.0.1 + +This error appears if you are using a CA certificate when you try to establish an internal connection using localhost. For example: + +``` +unable to request metadata: unable to dial: x509: cannot validate certificate for 127.0.0.1 because it doesn't contain any IP SANs +``` + +To fix this error, you must either specify the URL with a public domain or use self-signed certificates: + +[,bash] +---- +ifdef::env-kubernetes[kubectl exec redpanda-0 -c redpanda --namespace -- \] +rpk cluster info \ +-X brokers=: \ +-X tls.enabled=true +---- + +//end::tls[] + +ifdef::include-categories[] +== SASL issues + +This section addresses errors related to SASL (Simple Authentication and Security Layer), focusing on connection and authentication problems. + +endif::[] + +//tag::sasl[] +ifdef::env-kubernetes[] === Unable to continue with update: Secret When you use a YAML list to specify superusers, the Helm chart creates a Secret using the value of `auth.sasl.secretRef` as the Secret's name, and stores those superusers in the Secret. If the Secret already exists in the namespace when you deploy Redpanda, the following error is displayed: @@ -737,4 +604,18 @@ To fix this error, ensure that you use only one of the following methods to crea - `auth.sasl.secretRef` - `auth.sasl.users` + +endif::[] +=== Is SASL missing? + +This error appears when you try to interact with a cluster that has SASL enabled without passing a user's credentials. + +[.no-copy] +---- +unable to request metadata: broker closed the connection immediately after a request was issued, which happens when SASL is required but not provided: is SASL missing? +---- + +If you're using `rpk`, ensure to specify the `-X user`, `-X pass`, and `-X sasl.mechanism` flags. + +For all available flags, see the xref:reference:rpk/rpk-x-options.adoc[`rpk` options reference]. //end::sasl[] diff --git a/modules/upgrade/pages/k-rolling-upgrade.adoc b/modules/upgrade/pages/k-rolling-upgrade.adoc index dbea62013d..1d7cdc5064 100644 --- a/modules/upgrade/pages/k-rolling-upgrade.adoc +++ b/modules/upgrade/pages/k-rolling-upgrade.adoc @@ -313,7 +313,7 @@ Leaderless partitions: [] == Troubleshooting -include::manage:kubernetes/troubleshooting/k-troubleshoot.adoc[tags=deployment] +include::troubleshoot:partial$errors-and-solutions.adoc[tags=deployment] include::shared:partial$suggested-reading.adoc[] diff --git a/modules/upgrade/pages/migrate/kubernetes/helm-to-operator.adoc b/modules/upgrade/pages/migrate/kubernetes/helm-to-operator.adoc index ff19b5a78a..c1190f752c 100644 --- a/modules/upgrade/pages/migrate/kubernetes/helm-to-operator.adoc +++ b/modules/upgrade/pages/migrate/kubernetes/helm-to-operator.adoc @@ -181,7 +181,7 @@ After completing these steps, the Redpanda Operator is no longer managing your H While the deployment process can sometimes take a few minutes, a prolonged 'not ready' status may indicate an issue. -include::manage:kubernetes/troubleshooting/k-troubleshoot.adoc[tags=deployment] +include::troubleshoot:partial$errors-and-solutions.adoc[tags=deployment] For more troubleshooting steps, see xref:manage:kubernetes/troubleshooting/k-troubleshoot.adoc[Troubleshoot Redpanda in Kubernetes]. diff --git a/modules/upgrade/pages/rolling-upgrade.adoc b/modules/upgrade/pages/rolling-upgrade.adoc index 322a461b97..55a2328995 100644 --- a/modules/upgrade/pages/rolling-upgrade.adoc +++ b/modules/upgrade/pages/rolling-upgrade.adoc @@ -68,7 +68,7 @@ Example output: [,bash,subs="attributes+"] ---- -v{full-version} (rev {latest-release-commit}) +{latest-redpanda-tag} (rev {latest-release-commit}) ---- [NOTE] @@ -107,7 +107,7 @@ include::partial$rolling-upgrades/post-upgrade-tasks.adoc[] == Troubleshooting -include::manage:partial$troubleshooting.adoc[tags=deployment] +include::troubleshoot:partial$errors-and-solutions.adoc[tags=deployment] include::shared:partial$suggested-reading.adoc[] diff --git a/package-lock.json b/package-lock.json index 7fe4aa10c4..6fbdb94c67 100644 --- a/package-lock.json +++ b/package-lock.json @@ -2773,9 +2773,10 @@ } }, "node_modules/@redpanda-data/docs-extensions-and-macros": { - "version": "3.7.2", - "resolved": "https://registry.npmjs.org/@redpanda-data/docs-extensions-and-macros/-/docs-extensions-and-macros-3.7.2.tgz", - "integrity": "sha512-k7ln8KO+QyL2ieIlySx97k/C04eSOebnvUeuPwGzdzPfbc9NpC+QBOItgOurfdtWg2NsKWZpD3E+GZU5deWcDg==", + "version": "3.8.0", + "resolved": "https://registry.npmjs.org/@redpanda-data/docs-extensions-and-macros/-/docs-extensions-and-macros-3.8.0.tgz", + "integrity": "sha512-S4ssVauyULIqHFrRVX7ymIkHpNQo/f+D/4ENt4B3kKK1ISwlpcHIoAi4sVe6tdztO567oRp3ZMKAC9qx2mef3Q==", + "license": "ISC", "dependencies": { "@asciidoctor/tabs": "^1.0.0-beta.6", "@octokit/core": "^6.1.2", diff --git a/package.json b/package.json index 05cc1d7044..8929c32548 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,7 @@ "serve": "wds --node-resolve --open / --watch --root-dir docs --port 5002", "start": "cross-env-shell LIVERELOAD=true npx gulp", "test-console-docs": "cd setup-tests && npx doc-detective runTests --input ../modules/console/pages/quickstart.adoc -l debug", + "test-get-started-docs": "cd setup-tests && npx doc-detective runTests --input ../modules/get-started/pages/quick-start.adoc -l debug", "test-docs": "cd setup-tests && npx doc-detective runTests --input ../modules -l debug" }, "dependencies": { diff --git a/setup-tests/fetch-versions-and-rpk.json b/setup-tests/fetch-versions-and-rpk.json index 5e0ee1efb7..63b9d3932e 100644 --- a/setup-tests/fetch-versions-and-rpk.json +++ b/setup-tests/fetch-versions-and-rpk.json @@ -14,7 +14,11 @@ "setVariables": [ { "name": "REDPANDA_CONSOLE_VERSION", - "regex": ".*" + "regex": "(?<=CONSOLE_VERSION=)(.*)" + }, + { + "name": "CONSOLE_DOCKER_REPO", + "regex": "(?<=CONSOLE_DOCKER_REPO=)(.*)" } ] }, @@ -24,7 +28,11 @@ "setVariables": [ { "name": "REDPANDA_VERSION", - "regex": ".*" + "regex": "(?<=REDPANDA_VERSION=)(.*)" + }, + { + "name": "REDPANDA_DOCKER_REPO", + "regex": "(?<=REDPANDA_DOCKER_REPO=)(.*)" } ] }, diff --git a/setup-tests/redpanda-versions/fetch-console.js b/setup-tests/redpanda-versions/fetch-console.js index 262a25acfe..6cf7590648 100644 --- a/setup-tests/redpanda-versions/fetch-console.js +++ b/setup-tests/redpanda-versions/fetch-console.js @@ -1,10 +1,32 @@ -const semver = require("semver"); +// Import the version fetcher module +const GetLatestConsoleVersion = require('../../node_modules/@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/get-latest-console-version.js'); +const yaml = require('../../node_modules/js-yaml/index.js'); +const fs = require('fs'); + const owner = 'redpanda-data'; const repo = 'console'; +const CONSOLE_DOCKER_REPO = 'console' + +function getPrereleaseFromAntora() { + try { + const fileContents = fs.readFileSync('../antora.yml', 'utf8'); + const antoraConfig = yaml.load(fileContents); + return antoraConfig.prerelease === true; + } catch (error) { + console.error("Error reading antora.yml:", error); + return false; + } +} + +// Set beta based on the prerelease field in antora.yml or fallback to environment variable +const beta = getPrereleaseFromAntora() +// GitHub Octokit initialization async function loadOctokit() { const { Octokit } = await import('@octokit/rest'); - if (!process.env.REDPANDA_GITHUB_TOKEN) return new Octokit() + if (!process.env.REDPANDA_GITHUB_TOKEN) { + return new Octokit(); + } return new Octokit({ auth: process.env.REDPANDA_GITHUB_TOKEN, }); @@ -13,28 +35,26 @@ async function loadOctokit() { (async () => { try { const github = await loadOctokit(); - // Fetch the latest 10 releases - const releases = await github.rest.repos.listReleases({ - owner, - repo, - per_page: 10, - }); - // Filter valid semver tags and sort them - const sortedReleases = releases.data - .map(release => release.tag_name.replace(/^v/, '')) - .filter(tag => semver.valid(tag)) - // Sort in descending order to get the highest version first - .sort(semver.rcompare); - - if (sortedReleases.length > 0) { - console.log(sortedReleases[0]); - } else { - console.log("No valid semver releases found."); - process.exit(1) + const results = await Promise.allSettled([ + GetLatestConsoleVersion(github, owner, repo), + ]); + const LatestConsoleVersion = results[0].status === 'fulfilled' ? results[0].value : null; + if (!LatestConsoleVersion) { + throw new Error('Failed to fetch the latest Redpanda version'); } + // Determine the release version based on the beta flag, with a fallback to stable release if RC is null + const latestConsoleReleaseVersion = beta + ? (LatestConsoleVersion.latestBetaRelease + ? LatestConsoleVersion.latestBetaRelease + : `${LatestConsoleVersion.latestStableRelease}`) + : `${LatestConsoleVersion.latestStableRelease}`; + + // Print both version and Docker repo for Doc Detective to capture + console.log(`CONSOLE_VERSION=${latestConsoleReleaseVersion}`); + console.log(`CONSOLE_DOCKER_REPO=${CONSOLE_DOCKER_REPO}`); } catch (error) { console.error(error); - process.exit(1) + process.exit(1); } -})() \ No newline at end of file +})(); \ No newline at end of file diff --git a/setup-tests/redpanda-versions/fetch-redpanda.js b/setup-tests/redpanda-versions/fetch-redpanda.js index 514d346d0a..99fc5b0a01 100644 --- a/setup-tests/redpanda-versions/fetch-redpanda.js +++ b/setup-tests/redpanda-versions/fetch-redpanda.js @@ -1,10 +1,36 @@ +// Import the version fetcher module +const GetLatestRedpandaVersion = require('../../node_modules/@redpanda-data/docs-extensions-and-macros/extensions/version-fetcher/get-latest-redpanda-version.js'); +const yaml = require('../../node_modules/js-yaml/index.js'); +const fs = require('fs'); + // Fetch the latest release version from GitHub const owner = 'redpanda-data'; +function getPrereleaseFromAntora() { + try { + const fileContents = fs.readFileSync('../antora.yml', 'utf8'); + const antoraConfig = yaml.load(fileContents); + return antoraConfig.prerelease === true; + } catch (error) { + console.error("Error reading antora.yml:", error); + return false; + } +} + +// Set beta based on the prerelease field in antora.yml or fallback to environment variable +const beta = getPrereleaseFromAntora() +// Conditionally set DOCKER_REPO for subsequent test steps such as the Docker Compose file +if (beta) { + REDPANDA_DOCKER_REPO = 'redpanda-unstable'; +} else { + REDPANDA_DOCKER_REPO = 'redpanda'; +} const repo = 'redpanda'; async function loadOctokit() { const { Octokit } = await import('@octokit/rest'); - if (!process.env.REDPANDA_GITHUB_TOKEN) return new Octokit() + if (!process.env.REDPANDA_GITHUB_TOKEN) { + return new Octokit(); + } return new Octokit({ auth: process.env.REDPANDA_GITHUB_TOKEN, }); @@ -13,22 +39,29 @@ async function loadOctokit() { (async () => { try { const github = await loadOctokit(); - // Fetch the latest release - const release = await github.rest.repos.getLatestRelease({ owner, repo }); - const tag = release.data.tag_name; - latestRedpandaReleaseVersion = tag.replace('v', ''); + const results = await Promise.allSettled([ + GetLatestRedpandaVersion(github, owner, repo), + ]); + + const LatestRedpandaVersion = results[0].status === 'fulfilled' ? results[0].value : null; - // Get reference of the tag - const tagRef = await github.rest.git.getRef({ owner, repo, ref: `tags/${tag}` }); - const releaseSha = tagRef.data.object.sha; + if (!LatestRedpandaVersion) { + throw new Error('Failed to fetch the latest Redpanda version'); + } + // Determine the release version based on the beta flag, with a fallback to stable release if RC is null + const latestRedpandaReleaseVersion = beta + ? (LatestRedpandaVersion.latestRcRelease && LatestRedpandaVersion.latestRcRelease.version + ? LatestRedpandaVersion.latestRcRelease.version + : `${LatestRedpandaVersion.latestRedpandaRelease.version}`) + : `${LatestRedpandaVersion.latestRedpandaRelease.version}`; - // Get the tag object to extract the commit hash - const tagData = await github.rest.git.getTag({ owner, repo, tag_sha: releaseSha }); - latestRedpandaReleaseCommitHash = tagData.data.object.sha.substring(0, 7); + if (!LatestRedpandaVersion.latestRcRelease) REDPANDA_DOCKER_REPO = 'redpanda' - console.log(latestRedpandaReleaseVersion); + // Print both version and Docker repo for Doc Detective to capture + console.log(`REDPANDA_VERSION=${latestRedpandaReleaseVersion}`); + console.log(`REDPANDA_DOCKER_REPO=${REDPANDA_DOCKER_REPO}`); } catch (error) { console.error(error); - process.exit(1) + process.exit(1); } -})() \ No newline at end of file +})(); diff --git a/tools/add-caret-external-links.py b/tools/add-caret-external-links.py index 804d1bfb36..4910d5ef82 100644 --- a/tools/add-caret-external-links.py +++ b/tools/add-caret-external-links.py @@ -40,8 +40,7 @@ def replace_link(match): 'reference\\pages\\k-console-helm-spec.adoc', 'reference\\pages\\crd.adoc', 'reference\\pages\\k-redpanda-helm-spec.adoc', - 'reference\\partials\\bundle-contents-k8s.adoc', - 'reference\\partials\\bundle-contents-linux.adoc' + 'reference\\partials\\bundle-contents.adoc' ] # Function to process all .adoc files in a directory