redhat-developer / app-services-guides Goto Github PK

By default, new Kafka instances are only accessible by their owner, and the owner must grant additional access to the instance via ACL creation in order to do so.

Since rhoas cluster connect uses a service account to create a Kafka binding, we need to ensure that this account has the necessary ACLs, otherwise it will fail.

There should be a step showing how to add ACLs for the created service account. This can be achieved using the rhoas kafka acl grant-access command.

Give a service account produce and consume access on all topics:

rhoas kafka acl grant-access --producer --consumer --service-account <client-id> --topic "*" --group "*"

This command should be run after running rhoas cluster connect.

Open the guide

and observe the === Creating Kafka, === Installing Operator sections and the rest..

The "bin scripts" quickstart expects to replace <bootstrap_server> with the actual URL. But it does not say that explicitly so people might not notice and just use a command and get an error (the error message is descriptive enough though). Also, it does not say where to look at to see what the URL actually is.

Refactoring done in the #82 will enable us to link also other guide (as subthree or commit it directly here)
this way we could provide both Node.js and Quarkus examples.

What can be done:

1. Create Node.js SBO guide for Kafka
2. Link or commit sample Node.js Kafka application

CC @mhdawson

End user reported for us that guides repository (it is returned in google search/acces.redhat.com resources are not) are broken so users cannot reach proper guides from repo:

FYI @redhat-developer/app-services-docs

In Commands for managing Kafka we only list the commands which were not covered in previous sections.

It makes sense to list all Kafka commands here, regardless of whether or not they've been covered already. Users would like to see these at a glance.

Additionally, if we changed the code examples from in-line snippets to code blocks then GitHub Asciidoc rendering should display a button to copy the content, which it does not currently.

CC @secondsun

We need to validate guides per release.

@rkubis FYI

Here are a few suggestions to change in the app. I haven't tried them to see if they break the app or not.
cc @carlesarnal

• Provide a default value for ${OAUTH_REALM} such as ${OAUTH_REALM:rhoas}
• Change io.apicurio.registry.serde.avro.strategy.RecordIdStrategy to io.apicurio.registry.serde.strategy.TopicIdStrategy The latter is what the UI will display if the strategy is used. This changes should be in both producer and processor application.properties

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

These problems occurred while renovating this repository. View logs.

• WARN: Update versions are not valid

Datasource	Name	Replacement PR?
npm	npm-run-all

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• fix(deps): update dependency @redhat-cloud-services/frontend-components-config to v4.7.3
• fix(deps): update shared components packages (@patternfly/quickstarts, @patternfly/react-core, @rhoas/app-services-ui-shared, @webpack-cli/serve, JamesIves/github-pages-deploy-action, ajv, asciidoctor, copy-webpack-plugin, css-loader, css-minimizer-webpack-plugin, fs-extra, glob, html-webpack-plugin, jest, maven, mini-css-extract-plugin, node, node-fetch, npm-run-all, patternfly, registry.access.redhat.com/ubi8/ubi-minimal, style-loader, sync-fetch, terser-webpack-plugin, ts-loader, tsconfig-paths-webpack-plugin, tslib, typescript, webpack, webpack-bundle-analyzer, webpack-cli, webpack-dev-server, webpack-merge, io.strimzi:kafka-oauth-client, io.apicurio:apicurio-common-rest-client-vertx, org.testcontainers:kafka, org.apache.maven.plugins:maven-failsafe-plugin, org.apache.maven.plugins:maven-surefire-plugin, io.quarkus:quarkus-maven-plugin, io.quarkus:quarkus-bom, io.quarkus:quarkus-universe-bom, org.apache.maven.plugins:maven-compiler-plugin)
• fix(deps): update dependency @redhat-cloud-services/frontend-components-config to v6
• fix(deps): update shared components packages (major) (@patternfly/quickstarts, @patternfly/react-core, @webpack-cli/serve, actions/checkout, actions/setup-java, actions/setup-node, asciidoctor, copy-webpack-plugin, css-loader, css-minimizer-webpack-plugin, fs-extra, gh-pages, glob, jest, jsdom, mkdirp, node, node-fetch, quay.io/quarkus/quarkus-distroless-image, rimraf, style-loader, svg-url-loader, tsconfig-paths-webpack-plugin, typescript, webpack-cli, webpack-dev-server, webpack-merge, yaml, io.quarkus:quarkus-maven-plugin, io.quarkus:quarkus-bom, io.quarkus:quarkus-universe-bom)
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

Hi

Repository is being used for different purposes and I would like to see if we can clean up it little bit.
Also I think we might simply have different folder for the guide that is not quickstarts. etc.

1. All guides that are cloudmosaic quickstarts should be in the quickstarts folder
2. Documentation like cli guide should be in the docs folder
3. Code samples should be in the examples folder (already agreed as part of the other issue ).
4. Openshift guides - temp - should be in console-quickstarts

This will need some tooling changes but it might be very good to clear things out for community to understand what comes where etc.

Having documentation in the docs folder will also allow us to render github pages for it if needed etc. while quickstarts will be typically in cloud.redhat.com etc.

In the rhoas installation and configuration guide, the version numbers don't add much value, and they have to be updated every time there is a new rhoas release. Propose that we remove the version numbers where able. If there are any instances where it makes sense to show the version number, we can just use a standard "replaceable" (for example, <version> instead of 0.32).

For reference, see redhat-developer/app-services-cli#826.

Operator: Done
KafkaCat: Done {Verified}
Bin Scripts: Done {Verified}
CLI: In progress. redhat-developer/app-services-cli#409

kafkacat was renamed to kcat in August 2021 due to trademark issues.

The kafkacat project was renamed to kcat in August 2021 to adhere to the Apache Software Foundation's (ASF) trademark policies. Apart from the name, nothing else was changed.

https://github.com/edenhill/kcat#what-happened-to-kafkacat

• Replace current content to the format.
• Provide more information in the readme about how to contribute
• Remove readme - generation can be done later.

https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1/guide/88e1487a-2a14-4b35-85b9-a7a2d67a37f3
in Prerequisites section:

• You’ve installed the rhoas CLI. For more information, see Installing the rhoas CLI.

that link is 404, correct URL seems to be
https://access.redhat.com/documentation/en-us/red_hat_openshift_application_services/1/guide/bb30ee92-9e0a-4fd6-a67f-aed8910d7da3

We going to swap both examples later in separate issues to values we have in env vars in our toolings

RHOAS_SERVICE_ACCOUNT_CLIENT_ID=srvc-a-fd-df7e-fdsf-b529-e6a24a557358
RHOAS_SERVICE_ACCOUNT_CLIENT_SECRET=asd-fsdf-4d1f-8963-6ab83de375aa
RHOAS_SERVICE_ACCOUNT_AUTH_TOKEN_URL=https://identity.api.openshift.com/auth/realms/rhoas/protocol/openid-connect/token

We need more specific envs to avoid overriding existing ones (like AWS tokens etc.)

Originally posted by @wtrocki in #322 (comment)

Using App Services with Quarkus, Using Service Binding with App Services, Creating new guide links are broken

Since this is a configuration very specific to Quarkus and Kafka I am not sure if it should be a generated output format in the service account commands. If so, the service accounts commands would be coupled to Kafka.
At the very least this can be documented in the guides.

quarkus.container-image.insecure=true
quarkus.kubernetes-client.trust-certs=true
quarkus.openshift.expose=true
quarkus.openshift.env.secrets=managed-kafka-credentials
quarkus.openshift.env.mapping.kafka-username.from-secret=managed-kafka-credentials
quarkus.openshift.env.mapping.kafka-username.with-key=username
quarkus.openshift.env.mapping.kafka-password.from-secret=managed-kafka-credentials
quarkus.openshift.env.mapping.kafka-password.with-key=password

%prod.kafka.bootstrap.servers=my-kafka-jdsfdfrj.kafka.devshift.org:443
%prod.kafka.security.protocol=SASL_SSL
%prod.kafka.sasl.mechanism=PLAIN
%prod.kafka.sasl.jaas.config=org.apache.kafka.common.security.plain.PlainLoginModule required \
    username="${KAFKA_USERNAME}" \
    password="${KAFKA_PASSWORD}";

1. We need to create new branch and make it default.
2. Done some experiments on this branch to see if renovate will pick that up

OCM downloads page had a "Get started" link to
https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1/guide/f520e427-cad2-40ce-823d-96234ccbc047 which returns 404.
I'm now updating it to
https://access.redhat.com/documentation/en-us/red_hat_openshift_streams_for_apache_kafka/1/guide/88e1487a-2a14-4b35-85b9-a7a2d67a37f3 which seems to be the current URL for same doc. But I worry the use of a UUID may cause it to change again in the future? Can we assume that link stable, or can you provide a better permalink?

https://github.com/redhat-developer/app-services-guides/blob/main/.build/utils/quickstart-adoc.js

Bug:{product-long} is not working on local

This PR was automatically merged and it broke quarkus quickstart.

Originally posted by @wtrocki in #168 (comment)

We need to provide OAUTH_TOKEN_ENDPOINT_URI in guides as users often ask where to get that value (2 different persons shared that feedback)

Basically the Kafka bin quick start wishes to "assume control" of the user experience. I tried 2 browsers so it seems the state is saved with the user id on the backend
https://www.screencast.com/t/MtvYsPcb

We're using some of the service icons multiple times on the quick start and documentation cards and this currently only supports base-64 formats. This format seems to cause some jagged edges with the icon.

This request is for:

1. Being able to support other image formats
2. Being able to optimize the page load by using CDN delivered images

cc: @pmuir @wtrocki

Mentions a group id here, it says consumers with the same id belong in the same group. Couldn't see where I find this id..

When I install rhoas CLI on Linux (Fedora 34, RHEL 7 Server) and I want to enable command completion on Zsh:

$ rhoas completion zsh > "${fpath[1]}/_rhoas"

I get permission denied error:

zsh: permission denied: /usr/share/zsh/site-functions/_rhoas

I get the same error when I try to enable command completion with sudo:

$ sudo rhoas completion zsh > "${fpath[1]}/_rhoas"

I am able workaround this issue when I generate command completion for rhoas into my $HOME directory and then I can move it with sudo to proper location:

$ rhoas completion zsh > _rhoas
$ mv _rhoas /usr/share/zsh/site-functions

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Location: renovate.json
Error type: Invalid JSON (parsing failed)
Message: Syntax error: expecting String near fig" ], }

The default build (mvn/mvnw clean install / package) fails if docker is not installed or running on the development host.

I don't know why but maybe the Windows OpenJDK doesn't come with any cert installed and therefore it can not connect to the Kafka instance, I think therefore we should suggest the user to use the Oracle JDK both for the Bin scripts and the Quarkus app

There is no prebuild executable of kakfacat for windows and is practically impossible to compile it, therefore we should suggest using the docker image, or install kafkacat on WSL

Currently we have 2 guides using the same codebase.
There is simple way to do it currently:

For env variables we can use env files rather than application properties.
This is not only better practice.

Guide for the env can require users to create env file with some content other wise quarkus kubernetes plugin config will kick in:

Reference:
https://quarkus.io/guides/config-reference

Currently some guides are part of the operator/some are in the guides.
We need to discuss what would be the untilate source for those and how we can automate publishing