This is an automated email from the ASF dual-hosted git repository. hanahmily pushed a commit to branch doc-operator in repository https://gitbox.apache.org/repos/asf/skywalking-swck.git
commit 10eaf9641d23f9043f3a29dd3fd3a801e6191cb1 Author: Gao Hongtao <[email protected]> AuthorDate: Mon Aug 29 04:32:04 2022 +0000 Add more details about how to deploy the operator based on a released package Signed-off-by: Gao Hongtao <[email protected]> --- README.md | 42 ++++++++++++++++++--------------- docs/operator.md | 72 ++++++++++++++++++++++++++++++++++++++------------------ 2 files changed, 72 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index ca7e94f..c088f3e 100644 --- a/README.md +++ b/README.md @@ -7,50 +7,54 @@ Apache SkyWalking Cloud on Kubernetes A bridge project between [Apache SkyWalking](https://github.com/apache/skywalking) and Kubernetes. -SWCK is a platform for the SkyWalking user, provisions, upgrades, maintains SkyWalking relevant components, and makes them work natively on Kubernetes. +SWCK is a platform for the SkyWalking user that provisions, upgrades, maintains SkyWalking relevant components, and makes them work natively on Kubernetes. # Features - 1. Java Agent Injector: Inject the java agent into the application pod natively. - 1. Operator: Provision and maintain SkyWalking backend components. - 1. Custom Metrics Adapter: Provides custom metrics come from SkyWalking OAP cluster for autoscaling by Kubernetes HPA +* Java Agent Injector: Inject the java agent into the application pod natively. + * Inject the java agent into the application pod. + * Leverage a global configuration to simplify the agent and injector setup. + * Use the annotation to customize specific workloads. + * Synchronize injecting status to `JavaAgent` CR for monitoring purposes. +* Operator: Provision and maintain SkyWalking backend components. +* Custom Metrics Adapter: Provides custom metrics coming from SkyWalking OAP cluster for autoscaling by Kubernetes HPA # Quick Start - * Go to the [download page](https://skywalking.apache.org/downloads/#SkyWalkingCloudonKubernetes) to download latest release manifest. +* Go to the [download page](https://skywalking.apache.org/downloads/#SkyWalkingCloudonKubernetes) to download the latest release binary, `skywalking-swck-<SWCK_VERSION>-bin.tgz`. Unarchive the package to +a folder named `skywalking-swck-<SWCK_VERSION>-bin` ## Java Agent Injector -The java agent injector share the same binary with the operator. Follow the installation procedure of the operator -to onboard the injector. +* Install the [Operator](#operator) +* Label the namespace with `swck-injection=enabled` -The injector can: +```shell +$ kubectl label namespace default(your namespace) swck-injection=enabled +``` -* Inject the java agent into the application pod. -* Leverage a global configuration to simplify the agent and injector setup. -* Use the annotation to customize specific workloads. -* Sync injecting status to `JavaAgent` CR for monitoring purpose. +* Add label `swck-java-agent-injected: "true"` to the workloads -For more details, please read [Java agent injector](docs/java-agent-injector.md) +For more details, please read [Java agent injector](/docs/java-agent-injector.md) ## Operator - * To install the operator in an existing cluster, make sure you have [`cert-manager`](https://cert-manager.io/docs/installation/) installed. - * Apply the manifests for the Controller and CRDs in release/config: +* To install the operator in an existing cluster, ensure you have [`cert-manager`](https://cert-manager.io/docs/installation/) installed. +* Apply the manifests for the Controller and CRDs in release/config: ``` - kubectl apply -f release/operator/config + kubectl apply -f skywalking-swck-<SWCK_VERSION>-bin/config/operator-bundle.yaml ``` For more details, please refer to [deploy operator](docs/operator.md) ## Custom Metrics Adapter - * Deploy OAP server by referring to Operator Quick Start. - * Apply the manifests for an adapter in release/adapter/config: +* Deploy the OAP server by referring to Operator Quick Start. +* Apply the manifests for an adapter in release/adapter/config: ``` - kubectl apply -f release/adapter/config + kubectl apply -f skywalking-swck-<SWCK_VERSION>-bin/config/adapter-bundle.yaml ``` For more details, please read [Custom metrics adapter](docs/custom-metrics-adapter.md) diff --git a/docs/operator.md b/docs/operator.md index c9ba27b..ca8fa9a 100644 --- a/docs/operator.md +++ b/docs/operator.md @@ -1,28 +1,62 @@ # Operator Usage Guide -## Guides of Operator Deployment -### Use kustomize to customise your deployment -1. Clone the source code: +In this guide, you will learn: + +* How to deploy the operator from a released package or scratch +* The core CRDs the operator supports + +## Operator Deployment + +You could provision the operator from a binary package or build from sources. + +### Binary Package + +* Go to the [download page](https://skywalking.apache.org/downloads/#SkyWalkingCloudonKubernetes) to download the latest release binary, `skywalking-swck-<SWCK_VERSION>-bin.tgz`. Unarchive the package to +a folder named `skywalking-swck-<SWCK_VERSION>-bin` +* To install the operator in an existing cluster, make sure you have [`cert-manager`](https://cert-manager.io/docs/installation/) installed. +* Apply the manifests for the Controller and CRDs in `config`: + +```sh +kubectl apply -f skywalking-swck-<SWCK_VERSION>-bin/config/operator-bundle.yaml +``` + +### Build from sources + +1. Download released [source package](https://skywalking.apache.org/downloads/#SkyWalkingCloudonKubernetes) or clone the source code: ```sh git clone [email protected]:apache/skywalking-swck.git ``` -2. Edit file `operator/config/default/kustomization.yaml` file to change your preferences. If you prefer to your private - docker image, a quick path to override `OPERATOR_IMG` environment variable : `export OPERATOR_IMG=<private registry>/controller:<tag>` +1. Build docker image from scratch. If you prefer to your private +docker image, a quick path to override `OPERATOR_IMG` environment variable : `export OPERATOR_IMG=<private registry>/controller:<tag>` + +```sh +export OPERATOR_IMG=controller +make -C operator docker-build +``` -3. Use `make` to generate the final manifests and deploy: +Then, push this image `controller:latest` to a repository where the operator's pod could pull from. +If you use a local `KinD` cluster: ```sh -make -C operator deploy +kind load docker-image controller ``` -4. Deploy the CRDs: +1. Customize resource configurations based the templates laid in `operator/config`. We use `kustomize` to build them, please refer to [kustomize](https://kustomize.io/) in case you don't familiar with its syntax. + +1. Install the CRDs to Kubernetes: ```sh make -C operator install ``` +1. Use `make` to generate the final manifests and deploy: + +```sh +make -C operator deploy +``` + ### Test your deployment 1. Deploy a sample OAP server, this will create an OAP server in the default namespace: @@ -31,13 +65,13 @@ make -C operator install curl https://raw.githubusercontent.com/apache/skywalking-swck/master/operator/config/samples/default.yaml | kubectl apply -f - ``` -2. Check the OAP server in Kubernetes: +1. Check the OAP server in Kubernetes: ```sh kubectl get oapserver ``` -2. Check the UI server in Kubernetes: +1. Check the UI server in Kubernetes: ```sh kubectl get ui @@ -55,13 +89,6 @@ kubectl --namespace skywalking-swck-system get pods kubectl --namespace skywalking-swck-system logs -f [name_of_the_controller_pod] ``` -## Custom manifests templates - -If you want to custom the manifests templates to generate dedicated Kubernetes resources, -please edit YAMLs in `pkg/operator/manifests`. -The last step is to rebuild `operator` by `make -C operator docker-build`. - - ## Custom Resource Define(CRD) The custom resources that the operator introduced are: @@ -100,13 +127,12 @@ It provides options for how to connect an `OAP`. The `Fetcher` custom resource definition (CRD) declaratively defines a desired Fetcher setup to run in a Kubernetes cluster. It provides options to configure OpenTelemetry collector, which fetches metrics to the deployed `OAP`. - ## Examples of the Operator There are some instant examples to represent the functions or features of the Operator. -- [Deploy OAP server and UI with default settings](./examples/default-backend.md) -- [Fetch metrics from the Istio control plane(istiod)](./examples/istio-controlplane.md) -- [Inject the java agent to pods](./examples/java-agent-injector-usage.md) -- [Deploy a storage](./examples/storage.md) -- [Deploy a Satellite](./examples/satellite.md) +* [Deploy OAP server and UI with default settings](./examples/default-backend.md) +* [Fetch metrics from the Istio control plane(istiod)](./examples/istio-controlplane.md) +* [Inject the java agent to pods](./examples/java-agent-injector-usage.md) +* [Deploy a storage](./examples/storage.md) +* [Deploy a Satellite](./examples/satellite.md)
