camunda
As a user I have a hard time to quickly start with C8 SM
Details (Problem)
I recently played around with C8 SM (as preparation for a Game day) and I simply installed the chart with all defaults.
Instead of using port-forwarding and doing everything local I wanted to be more realistic and deploy an application in K8 as well. I had a really hard time to find out what I have to do such my application can talk with Zeebe (meaning configure the right OAUTH stuff with Identity, etc.)
I was missing a simple quick start guide for this, and was wondering whether we don't have such thing? I haven't seen anything in the docs.
What I found were some blog entries from @nloding (which is great btw) but they didn't get far enough, for example:
- https://camunda.com/blog/2023/10/camunda-self-managed-for-absolute-beginners/
- https://camunda.com/blog/2024/01/camunda-self-managed-absolute-beginners-part-2-ingress-tls-ssl/
As user I had expected they might cover this, but this just ends with Add Identity and Optimize, configure the ingress, and test the authentication with zbctl
As this is actually the default anyway I don't think it is the best to place it into a blog. I would expect an get started guide for such in our documentation.
Even the current guide https://docs.camunda.io/docs/self-managed/setup/guides/installing-payment-app-example/ just links to a guide which explains everything with port-forwarding. I don't think that we expect to use such thing to be used in production.
Proposal
We place a quick get started or (go to production guide) that includes just install helm charts, do x,y,z and be happy.
For example, I wrote the following down here (these were the steps to achieve this):
Example guide:
Installation:
releaseName=c8-sm
helm install $releaseName camunda/camunda-platform
Will include:
- Identity, Keycloak, Postgres
- Tasklist, Operate, Optimize, Elasticsearch
- Zeebe Broker, Zeebe Gateway
Application deployment For example, we can use our starter deployment, that we use for our cloud benchmarks:
- Port-forward to keycloak kubectl port-forward svc/$releaseName-keycloak 18080:80
- Port-forward to identity kubectl port-forward svc/c8-sm-identity 8080:80
- Access http://localhost:8080/applications
- Check pre-configured Zeebe application - get the clientId and client secret
- Configure either the starter via environment variables or the secret as we do in our benchmarks (I recommend this)
The secret can look like this:
apiVersion: v1
kind: Secret
metadata:
name: cloud-credentials
type: Opaque
stringData:
clientId: zeebe # Copied from Identity
clientSecret: xxxxxxxxxx # Copied from Identity
# the prefix depends on your chart $releaseName; internally the application can resolve this name
zeebeAddress: c8-sm-zeebe-gateway:26500
# the prefix depends on your chart $releaseName; make sure to use the service name
authServer: http://c8-sm-keycloak/auth/realms/camunda-platform/protocol/openid-connect/token
Our starter deployment:
apiVersion: apps/v1
kind: Deployment
metadata:
name: starter
labels:
app: starter
spec:
selector:
matchLabels:
app: starter
replicas: 1
template:
metadata:
labels:
app: starter
metrics: gmp
spec:
containers:
- name: starter
image: gcr.io/zeebe-io/starter:SNAPSHOT
imagePullPolicy: Always
env:
- name: JDK_JAVA_OPTIONS
value: >-
-Dapp.starter.rate=5
-Dapp.tls=false
-Dzeebe.client.requestTimeout=62000
-XX:+HeapDumpOnOutOfMemoryError
- name: LOG_LEVEL
value: "info"
- name: ZEEBE_ADDRESS
valueFrom:
secretKeyRef:
name: cloud-credentials
key: zeebeAddress
- name: ZEEBE_CLIENT_ID
valueFrom:
secretKeyRef:
name: cloud-credentials
key: clientId
- name: ZEEBE_CLIENT_SECRET
valueFrom:
secretKeyRef:
name: cloud-credentials
key: clientSecret
- name: ZEEBE_AUTHORIZATION_SERVER_URL
valueFrom:
secretKeyRef:
name: cloud-credentials
key: authServer
- name: ZEEBE_TOKEN_SCOPE
value: "camunda-identity"
- name: ZEEBE_TOKEN_AUDIENCE
value: "zeebe-api"
resources:
limits:
cpu: 250m
memory: 256Mi
requests:
cpu: 250m
memory: 256Mi
If you now port forward to Operate kubectl port-forward svc/c8-sm-operate 8081:80 you will see new instances being created.
Maybe we can reuse this.
Looks like I followed the wrong link https://github.com/camunda-community-hub/camunda-8-examples/tree/main/payment-example-process-application
Instead of https://github.com/camunda-community-hub/camunda-8-examples/blob/main/payment-example-process-application/kube/README.md
Can we make this more accessible and visible (observable). WDYT @akeller ?
We have an E2E for MT + SM (which I don't think you are looking for) as well as getting started guide content in the works for different installation paths.
I don't think that we expect to use such thing to be used in production.
Getting started guides shouldn't be used in production, but they shouldn't necessarily block seeing features. We are having an internal discussion about this now - what is in scope for getting started vs. after. I want to draw a clear distinction between getting started vs. production build outs until it's super easy to do both quickly. This is not a topic that can just be fixed with docs.
However, based on your feedback, it looks like there are things we can take immediate action on.
@conceptualshark is our DRI of SM docs, and I want to make sure this is on your radar. Can you start to take a look at this feedback and see if there are any quick wins as you continue your onboarding? I will continue to pull you in to topics as they evolve or need your input.
FYI @maxdanilov, who is also part of this internal discussion. Super timely, as we just had a meeting today!
With our investment in C8Run as our getting started experience, this likely needs to be reworked or closed and rescoped. @conceptualshark can I assign this to you, but leave it in Blocked until you have a chance to review?
@akeller I've assigned this to myself for review/updating, but agree on leaving it in blocked for now - it also may be the case that we can do a better job of this once the 8.7 version of C8Run is release, which should include a few more features.
Closing this with @akeller as complete, any ongoing improvements will happen through the onboarding team.