Local Development
Let's get started with Hadron for local application development using Kubernetes and Kind.
Kind is a tool for running local Kubernetes clusters using Docker container “nodes” and is the easiest way to get started with Kubernetes.
Install Kind
Follow the instructions in the Kind installation guide to ensure kind is installed locally and ready for use.
Next, create a cluster.
kind create cluster
Once your cluster is up and running, you are ready to move on to the next step.
Install Hadron
Helm is the package manager for Kubernetes, and it will need to be installed and available for command-line usage for this use case. If you've been using Kubernetes for any amount of time, then you are probably already using helm.
Before we install the Hadron Operator, we are going to install cert-manager. Though cert-manager is not required by Hadron, it does greatly simplify the setup of TLS certificates, which Hadron uses for its validating webhooks. Instead of manually crafting our own certs, we'll stick with cert-manager.
helm repo add jetstack https://charts.jetstack.io
helm upgrade cert-manager jetstack/cert-manager --install --set installCRDs=true
Now we are ready to install the Hadron Operator:
# Helm >= v3.7.0 is required for OCI usage.
helm install hadron-operator oci://ghcr.io/hadron-project/charts/hadron-operator --version 0.1.3
Install Example Resources
For this use case, let's use the example resources found in the Hadron repo. Here is the code.
Apply the code to the cluster:
wget -qO- https://raw.githubusercontent.com/hadron-project/hadron/tree/main/charts/hadron-operator/examples/full.yaml | kubectl apply -f -
The example file is about 75 lines of code, so here we will only show the names and types of the resources for brevity.
apiVersion: hadron.rs/v1beta1
kind: Stream
metadata:
name: events
...
---
apiVersion: hadron.rs/v1beta1
kind: Pipeline
metadata:
name: service-creation
# ...
---
apiVersion: hadron.rs/v1beta1
kind: Token
metadata:
name: hadron-full-access
# ...
---
apiVersion: hadron.rs/v1beta1
kind: Token
metadata:
name: hadron-read-only
# ...
---
apiVersion: hadron.rs/v1beta1
kind: Token
metadata:
name: hadron-read-write
# ...
This example code defines a Stream, a Pipeline associated with that Stream, and 3 Tokens which can be used to experiment with Hadron's authentication and authorization system.
Application Integration
Integrating you application with Hadron involves three simple steps:
- Add the Hadron client as an application dependency. This is language dependent. In Rust, simply add
hadron-client = "0.1.0-beta.0"
to the[dependencies]
section of yourCargo.toml
. - Next, determine the access token which your application will use. For this use case, we'll use the
hadron-full-access
Token. - Finally, we need the URL to use for connecting to the Hadron Stream. This is always deterministic based on the name of the Stream itself, and follows the pattern:
http://{streamName}.{namespaceName}.svc.{clusterApex}:7000
.{streamName}
isevents
,{namespaceName}
isdefault
,{clusterApex}
defaults tocluster.local
in Kubernetes,- which all works out to
http://events.default.svc.cluster.local:7000
, - for details on how to connect from outside of the Kubernetes cluster, see the Streams reference.
Now that we have this info, let's define a Kubernetes Deployment which uses this info. In this case we will just be using the Hadron CLI to establish Stream subscriptions, but it will sufficiently demonstrate how to integrate an application using these details.
Create a file called deployment.yaml
with the following contents:
apiVersion: apps/v1
kind: Deployment
metadata:
name: demo-client
namespace: default
spec:
replicas: 3
selector:
matchLabels:
app: demo-client
template:
metadata:
labels:
app: demo-client
spec:
containers:
- name: cli
image: ghcr.io/hadron-project/hadron/hadron-cli:latest
command: ["hadron", "stream", "sub", "--group=demo-client", "--start-beginning"]
env:
- name: HADRON_TOKEN
valueFrom:
secretKeyRef:
name: hadron-full-access
key: token
- name: HADRON_URL
value: http://events.default.svc.cluster.local:7000
Now apply this file to the cluster:
kubectl apply -f deployment.yaml
This will create a new deployment, with 3 replicas, and each replica pod will be running an instance of the Hadron CLI. The CLI will create a subscription to all partitions of the Stream events
, and will print the contents of each event it receives and will then ack
the event.
Next Steps
From here, some good next steps may be:
- Make some changes: you've made it pretty far through the guide! Now might be a good time to try some experimentation of your own.
- Model application workflows: start modeling your own application workflows by encoding them as Pipelines. Start writing your client code for publishing application events to your Stream, and then write the code which will process the various stages of your Pipelines. Check out the Use Case: Service Provisioning for some deeper exploration.
- Prepare for Production deployment: reviewing the reference sections for Hadron's resources is a great way to prepare for deploying Hadron in a production environment. Streams have various configuration options which can be tuned for scaling, storage, resource quotas and the like.