diff --git a/README.md b/README.md index 6a4f300..552e85d 100644 --- a/README.md +++ b/README.md @@ -1,105 +1,122 @@ -# coder-logstream-kube +
+

coder-logstream-kube

+

Stream Kubernetes Pod events to Coder startup logs

-[![discord](https://img.shields.io/discord/747933592273027093?label=discord)](https://discord.gg/coder) -[![release](https://img.shields.io/github/v/tag/coder/coder-logstream-kube)](https://github.com/coder/envbuilder/pkgs/container/coder-logstream-kube) -[![godoc](https://pkg.go.dev/badge/github.com/coder/coder-logstream-kube.svg)](https://pkg.go.dev/github.com/coder/coder-logstream-kube) -[![license](https://img.shields.io/github/license/coder/coder-logstream-kube)](./LICENSE) + [Installation](#installation) | [Configuration](#configuration) | [Development](#development) -Stream Kubernetes Pod events to the Coder startup logs. + [![discord](https://img.shields.io/discord/747933592273027093?label=discord)](https://discord.gg/coder) + [![release](https://img.shields.io/github/v/tag/coder/coder-logstream-kube)](https://github.com/coder/coder-logstream-kube/pkgs/container/coder-logstream-kube) + [![godoc](https://pkg.go.dev/badge/github.com/coder/coder-logstream-kube.svg)](https://pkg.go.dev/github.com/coder/coder-logstream-kube) + [![license](https://img.shields.io/github/license/coder/coder-logstream-kube)](./LICENSE) +
-- Easily determine the reason for a pod provision failure, or why a pod is stuck in a pending state. -- Visibility into when pods are OOMKilled, or when they are evicted. -- Filter by namespace, field selector, and label selector to reduce Kubernetes API load. +--- + +- Easily determine the reason for a pod provision failure, or why a pod is stuck pending +- Visibility into when pods are OOMKilled or evicted +- Filter by namespace, field selector, and label selector to reduce Kubernetes API load ![Log Stream](./scripts/demo.png) -## Usage +## Installation -Apply the Helm chart to start streaming logs into your Coder instance: +Deploy via Helm chart: ```console helm repo add coder-logstream-kube https://helm.coder.com/logstream-kube helm install coder-logstream-kube coder-logstream-kube/coder-logstream-kube \ --namespace coder \ - --set url= + --set url= ``` -> **Multi-Namespace support** -> -> By default, coder-logstream-kube will watch all namespaces in the cluster. To limit which namespaces are monitored, you can specify them in the [values.yaml](helm/values.yaml) file: -> -> ```yaml -> # Watch specific namespaces only -> namespaces: ["default", "kube-system"] -> -> # Watch all namespaces (default) -> namespaces: [] -> ``` -> -> When `namespaces` is empty or not specified, the service will monitor all namespaces in the cluster. +For additional customization (image, pull secrets, annotations, etc.), see the [values.yaml](helm/values.yaml) file. + +## Configuration + +### Multi-Namespace Support + +By default, coder-logstream-kube will watch all namespaces in the cluster. To limit which namespaces are monitored, you can specify them in the [values.yaml](helm/values.yaml) file: + +```yaml +# Watch specific namespaces only +namespaces: ["default", "kube-system"] + +# Watch all namespaces (default) +namespaces: [] +``` + +When `namespaces` is empty or not specified, the service will monitor all namespaces in the cluster. > **Note** -> For additional customization (such as customizing the image, pull secrets, annotations, etc.), you can use the -> [values.yaml](helm/values.yaml) file directly. +> For additional customization (such as customizing the image, pull secrets, annotations, etc.), you can use the [values.yaml](helm/values.yaml) file directly. + +### CLI Flags / Environment Variables + +| Flag | Env Var | Description | +|------|---------|-------------| +| `--coder-url`, `-u` | `CODER_URL` | URL of the Coder instance (required) | +| `--namespaces`, `-n` | `CODER_NAMESPACES` | Comma-separated list of namespaces to watch | +| `--field-selector`, `-f` | `CODER_FIELD_SELECTOR` | Kubernetes field selector for filtering pods | +| `--label-selector`, `-l` | `CODER_LABEL_SELECTOR` | Kubernetes label selector for filtering pods | +| `--kubeconfig`, `-k` | - | Path to kubeconfig file (default: `~/.kube/config`) | + +### Custom Certificates + +- [`SSL_CERT_FILE`](https://go.dev/src/crypto/x509/root_unix.go#L19): Path to an SSL certificate file +- [`SSL_CERT_DIR`](https://go.dev/src/crypto/x509/root_unix.go#L25): Directory to check for SSL certificate files + +## Template Setup -Your Coder template should be using a `kubernetes_deployment` resource with `wait_for_rollout` set to `false`. +Your Coder template should use a `kubernetes_deployment` resource with `wait_for_rollout` set to `false`: ```hcl resource "kubernetes_deployment" "hello_world" { - count = data.coder_workspace.me.start_count + count = data.coder_workspace.me.start_count wait_for_rollout = false ... } ``` -This ensures all pod events will be sent during initialization and startup. +This ensures all pod events are captured during initialization and startup. -## How? - -Kubernetes provides an [informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod and event data from the API server. - -`coder-logstream-kube` listens for pod creation events with containers that have the `CODER_AGENT_TOKEN` environment variable set. All pod events are streamed as logs to the Coder API using the agent token for authentication. +## Development -## Custom Certificates +### Makefile Targets -- [`SSL_CERT_FILE`](https://go.dev/src/crypto/x509/root_unix.go#L19): Specifies the path to an SSL certificate. -- [`SSL_CERT_DIR`](https://go.dev/src/crypto/x509/root_unix.go#L25): Identifies which directory to check for SSL certificate files. +```console +make help # Show all available targets +make build # Build the project +make test # Run unit tests +make test/integration # Run integration tests (requires KinD) +make lint # Run golangci-lint and shellcheck +make fmt # Format Go and shell code +``` -## Development +### Integration Tests -### Running Tests +Integration tests run against a real Kubernetes cluster using [KinD](https://kind.sigs.k8s.io/). -Unit tests can be run with: +**Prerequisites:** [Docker](https://docs.docker.com/get-docker/), [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation), [kubectl](https://kubernetes.io/docs/tasks/tools/) ```console -go test ./... -race +make kind/create # Create KinD cluster +make test/integration # Run integration tests +make kind/delete # Clean up ``` -### Integration Tests +## How It Works -Integration tests run against a real Kubernetes cluster using [KinD (Kubernetes in Docker)](https://kind.sigs.k8s.io/). +Kubernetes provides an [informers](https://pkg.go.dev/k8s.io/client-go/informers) API that streams pod and event data from the API server. -**Prerequisites:** -- [Docker](https://docs.docker.com/get-docker/) -- [KinD](https://kind.sigs.k8s.io/docs/user/quick-start/#installation) -- [kubectl](https://kubernetes.io/docs/tasks/tools/) +`coder-logstream-kube` listens for Pod and ReplicaSet events with containers that have the `CODER_AGENT_TOKEN` environment variable set. All events are streamed as logs to the Coder API using the agent token for authentication. -**Setup and run:** +## Support -```console -# Create a KinD cluster -./scripts/kind-setup.sh create +Feel free to [open an issue](https://github.com/coder/coder-logstream-kube/issues/new) if you have questions, run into bugs, or have a feature request. -# Run integration tests -go test -tags=integration -v ./... +[Join our Discord](https://discord.gg/coder) to provide feedback and chat with the community! -# Clean up when done -./scripts/kind-setup.sh delete -``` +## License -The integration tests validate: -- Pod event streaming with real Kubernetes informers -- ReplicaSet event handling -- Multi-namespace support -- Label selector filtering +[AGPL-3.0](./LICENSE) diff --git a/scripts/demo.png b/scripts/demo.png index c5ef945..d4d4c45 100644 Binary files a/scripts/demo.png and b/scripts/demo.png differ