Cherry-pick doc commits to release-0.1 (#221)

* Include steps to create istio-cni ns when missing (#174) Signed-off-by: Sridhar Gaddam <sgaddam@redhat.com> Signed-off-by: bmangoen <bmangoen@redhat.com> * Fix minor typos in e2e readme file (#176) Signed-off-by: Sridhar Gaddam <sgaddam@redhat.com> Signed-off-by: bmangoen <bmangoen@redhat.com> * Display a friendly message for missing K8s cluster (#175) Some of the Makefile commands require a running K8s cluster. When these commands are issued without an active cluster, we currently do not display a proper message, and users have to figure it out manually. This PR fixes that by verifying access to a running cluster and displaying a friendly message if not. Signed-off-by: Sridhar Gaddam <sgaddam@redhat.com> Signed-off-by: bmangoen <bmangoen@redhat.com> * Add docs for sail-operator installation using CLI (#171) * Add installation with CLI doc Signed-off-by: bmangoen <bmangoen@redhat.com> * Use 0.1-nightly channel Signed-off-by: bmangoen <bmangoen@redhat.com> --------- Signed-off-by: bmangoen <bmangoen@redhat.com> * Prerequisites for installing using CLI (#179) Signed-off-by: bmangoen <bmangoen@redhat.com> * Add user docs for addons (#187) * Add user docs for addons Signed-off-by: Nick Fox <nfox@redhat.com> * Apply suggestions from code review Co-authored-by: Sridhar Gaddam <sgaddam@redhat.com> --------- Signed-off-by: Nick Fox <nfox@redhat.com> Co-authored-by: Sridhar Gaddam <sgaddam@redhat.com> Signed-off-by: bmangoen <bmangoen@redhat.com> * Remove outdated comments from Dockerfile (#194) We're not planning on using distroles Signed-off-by: Daniel Grimm <dgrimm@redhat.com> Signed-off-by: bmangoen <bmangoen@redhat.com> * Add enhancements/ directory (#191) * Add enhancements/ directory I added an enhancement template and a first SEP that discusses the process Signed-off-by: Daniel Grimm <dgrimm@redhat.com> * Added `backward compatibility` section to template Signed-off-by: Daniel Grimm <dgrimm@redhat.com> * Wording Signed-off-by: Daniel Grimm <dgrimm@redhat.com> * Add a sentence about istio design doc Signed-off-by: Daniel Grimm <dgrimm@redhat.com> --------- Signed-off-by: Daniel Grimm <dgrimm@redhat.com> Signed-off-by: bmangoen <bmangoen@redhat.com> * Add helm-publish make target (#203) * Add helm-publish target Signed-off-by: bmangoen <bmangoen@redhat.com> * Add comment for helm-publish target Signed-off-by: bmangoen <bmangoen@redhat.com> --------- Signed-off-by: bmangoen <bmangoen@redhat.com> * #204 Update Redme with enhancement process information (#205) Signed-off-by: frherrer <frherrer@redhat.com> Signed-off-by: bmangoen <bmangoen@redhat.com> --------- Signed-off-by: Sridhar Gaddam <sgaddam@redhat.com> Signed-off-by: bmangoen <bmangoen@redhat.com> Signed-off-by: Nick Fox <nfox@redhat.com> Signed-off-by: Daniel Grimm <dgrimm@redhat.com> Signed-off-by: frherrer <frherrer@redhat.com> Co-authored-by: Sridhar Gaddam <sgaddam@redhat.com> Co-authored-by: Nick Fox <nick@nrfox.com> Co-authored-by: Daniel Grimm <dgrimm@redhat.com> Co-authored-by: Francisco Herrera <frherrer@redhat.com>
istio-ecosystem · Jul 19, 2024 · d72f6f0 · d72f6f0
1 parent 9b9be64
commit d72f6f0
Show file tree

Hide file tree

Showing 9 changed files with 297 additions and 19 deletions.
diff --git a/Dockerfile b/Dockerfile
@@ -1,7 +1,4 @@
-# Use distroless as minimal base image to package the manager binary
-# Refer to https://github.com/GoogleContainerTools/distroless for more details
 FROM registry.access.redhat.com/ubi9/ubi-minimal:latest 
-# gcr.io/distroless/static:nonroot
 
 ARG TARGETOS TARGETARCH
 

diff --git a/Makefile.core.mk b/Makefile.core.mk
@@ -251,68 +251,80 @@ docker-buildx: build-all ## Build and push docker image with cross-platform supp
 
 ##@ Deployment
 
+.PHONY: verify-kubeconfig
+verify-kubeconfig:
+	@kubectl get pods >/dev/null 2>&1 || (echo "Please verify that you have an active, running cluster and that KUBECONFIG is pointing to it." && exit 1)
+
 .PHONY: install
-install: gen-manifests ## Install CRDs into an existing cluster.
+install: verify-kubeconfig gen-manifests ## Install CRDs into an existing cluster.
 	kubectl create ns ${NAMESPACE} || echo "namespace ${NAMESPACE} already exists"
 	kubectl apply --server-side=true -f chart/crds
 
 .PHONY: uninstall
-uninstall: ## Uninstall CRDs from an existing cluster.
+uninstall: verify-kubeconfig ## Uninstall CRDs from an existing cluster.
 	kubectl delete --ignore-not-found -f chart/crds
 
 .PHONY: helm-package
 helm-package: helm ## Package the helm chart.
-	$(HELM) package chart
+	$(HELM) package chart --destination $(REPO_ROOT)/out
+
+.PHONY: helm-publish
+helm-publish: helm-package ## Create a GitHub release and upload the helm charts package to it.
+	export GITHUB_TOKEN=$(GITHUB_TOKEN)
+	gh release create $(VERSION) $(REPO_ROOT)/out/sail-operator-$(VERSION).tgz \
+		--target release-$(MINOR_VERSION) \
+		--title "sail-operator $(VERSION)" \
+		--generate-notes
 
 .PHONY: deploy
-deploy: helm ## Deploy controller to an existing cluster.
+deploy: verify-kubeconfig helm ## Deploy controller to an existing cluster.
 	$(info NAMESPACE: $(NAMESPACE))
 	kubectl create ns ${NAMESPACE} || echo "namespace ${NAMESPACE} already exists"
 	$(HELM) template chart chart $(HELM_TEMPL_DEF_FLAGS) --set image='$(IMAGE)' --namespace $(NAMESPACE) | kubectl apply --server-side=true -f -
 
 .PHONY: deploy-yaml
-deploy-yaml: helm ## Output YAML manifests used by `deploy`.
+deploy-yaml: verify-kubeconfig helm ## Output YAML manifests used by `deploy`.
 	$(HELM) template chart chart $(HELM_TEMPL_DEF_FLAGS) --set image='$(IMAGE)' --namespace $(NAMESPACE)
 
 .PHONY: deploy-openshift # TODO: remove this target and use deploy-olm instead (when we fix the internal registry TLS issues when using operator-sdk run bundle)
-deploy-openshift: helm ## Deploy controller to an existing OCP cluster.
+deploy-openshift: verify-kubeconfig helm ## Deploy controller to an existing OCP cluster.
 	$(info NAMESPACE: $(NAMESPACE))
 	kubectl create ns ${NAMESPACE} || echo "namespace ${NAMESPACE} already exists"
 	$(HELM) template chart chart $(HELM_TEMPL_DEF_FLAGS) --set image='$(IMAGE)' --namespace $(NAMESPACE) --set platform="openshift" | kubectl apply --server-side=true -f -
 
 .PHONY: deploy-yaml-openshift
-deploy-yaml-openshift: helm ## Output YAML manifests used by `deploy-openshift`.
+deploy-yaml-openshift: verify-kubeconfig helm ## Output YAML manifests used by `deploy-openshift`.
 	$(HELM) template chart chart $(HELM_TEMPL_DEF_FLAGS) --set image='$(IMAGE)' --namespace $(NAMESPACE) --set platform="openshift"
 
 .PHONY: deploy-olm
-deploy-olm: bundle bundle-build bundle-push ## Build and push the operator OLM bundle and deploy the operator using OLM.
+deploy-olm: verify-kubeconfig bundle bundle-build bundle-push ## Build and push the operator OLM bundle and deploy the operator using OLM.
 	kubectl create ns ${NAMESPACE} || echo "namespace ${NAMESPACE} already exists"
 	$(OPERATOR_SDK) run bundle $(BUNDLE_IMG) -n ${NAMESPACE}
 
 .PHONY: undeploy
-undeploy: ## Undeploy controller from an existing cluster.
+undeploy: verify-kubeconfig ## Undeploy controller from an existing cluster.
 	kubectl delete istios.operator.istio.io --all --all-namespaces --wait=true
 	$(MAKE) -e HELM_TEMPL_DEF_FLAGS="$(HELM_TEMPL_DEF_FLAGS)" deploy-yaml | kubectl delete --ignore-not-found -f -
 	kubectl delete ns ${NAMESPACE} --ignore-not-found
 	$(HELM) template chart chart $(HELM_TEMPL_DEF_FLAGS) --set image='$(IMAGE)' --namespace $(NAMESPACE) | kubectl delete --ignore-not-found -f -
 
 .PHONY: undeploy-olm
-undeploy-olm: operator-sdk ## Undeploy the operator from an existing cluster (used only if operator was installed via OLM).
+undeploy-olm: verify-kubeconfig operator-sdk ## Undeploy the operator from an existing cluster (used only if operator was installed via OLM).
 	kubectl delete istios.operator.istio.io --all --all-namespaces --wait=true
 	$(OPERATOR_SDK) cleanup $(OPERATOR_NAME) --delete-all -n ${NAMESPACE}
 
 .PHONY: deploy-example
 deploy-example: deploy-example-openshift ## Deploy an example Istio resource to an existing OCP cluster. Same as `deploy-example-openshift`.
 
 .PHONY: deploy-example-openshift
-deploy-example-openshift: ## Deploy an example Istio and IstioCNI resource to an existing OCP cluster.
+deploy-example-openshift: verify-kubeconfig ## Deploy an example Istio and IstioCNI resource to an existing OCP cluster.
 	kubectl create ns istio-cni || echo "namespace istio-cni already exists"
 	kubectl apply -f chart/samples/istiocni-sample.yaml
 	kubectl create ns istio-system || echo "namespace istio-system already exists"
 	kubectl apply -f chart/samples/istio-sample-openshift.yaml
 
 .PHONY: deploy-example-kubernetes
-deploy-example-kubernetes: ## Deploy an example Istio resource on an existing cluster.
+deploy-example-kubernetes: verify-kubeconfig ## Deploy an example Istio resource on an existing cluster.
 	kubectl create ns istio-system || echo "namespace istio-system already exists"
 	kubectl apply -f chart/samples/istio-sample-kubernetes.yaml
 

diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ This document aims to provide an overview of the project and some information fo
     - [Integration Tests](#integration-tests)
     - [End-to-End Tests](#end-to-end-tests)
 - [Community Support and Contributing](#community-support-and-contributing)
+- [Sail Enhancement Proposal](#sail-enhancement-proposal)
 - [Issue management](#issue-management)
 
 ## How it works
@@ -117,6 +118,8 @@ kubectl apply -f chart/samples/istio-sample-openshift.yaml
 On OpenShift, you must also deploy the Istio CNI plugin by creating an instance of the `IstioCNI` resource:
 
 ```sh
+# Create the istio-cni namespace if it does not exist
+kubectl get ns istio-cni || kubectl create ns istio-cni
 kubectl apply -f chart/samples/istiocni-sample.yaml
 ```
 
@@ -168,6 +171,8 @@ make run
 
 ### Modifying the API definitions
 
+**Important:** Any API change should be discussed in an [SEP](https://github.com/istio-ecosystem/sail-operator/blob/main/enhancements/SEP1-enhancement-process.md) before being implemented.
+
 If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
 
 ```sh
@@ -213,6 +218,12 @@ make test.e2e.ocp
 ## Community Support and Contributing
 Please refer to the [CONTRIBUTING-SAIL-PROJECT.md](https://github.com/istio-ecosystem/sail-operator/blob/main/CONTRIBUTING.md) file for more information on how to contribute to the sail-operator project. This file contains all the information you need to get started with contributing to the project.
 
+## Sail Enhancement Proposal
+
+SEP documents are used to propose and discuss non-trivial features or epics and any API changes. Please refer to the [SEP1-enhancement-process.md](https://github.com/istio-ecosystem/sail-operator/blob/main/enhancements/SEP1-enhancement-process.md) file for more information on how to create a Sail Enhancement Proposal (SEP) for the sail-operator project.
+
+SEP documents are stored in the [enhancements](https://github.com/istio-ecosystem/sail-operator/tree/main/enhancements) directory of the sail-operator repository in Markdown format. If you want to create a SEP, be sure to check out the [SEP template](https://github.com/istio-ecosystem/sail-operator/blob/main/enhancements/SEP0-template.md).
+
 ## Issue management
 Please refer to the [ISSUE-MANAGEMENT.md](https://github.com/istio-ecosystem/sail-operator/blob/main/ISSUE-MANAGEMENT.md) file for more information on how to report bugs and feature requests to the sail-operator team.
 

diff --git a/docs/README.md b/docs/README.md
@@ -10,6 +10,8 @@ tbd
 
 ### Installation on OpenShift
 
+#### Installing through the web console
+
 1. In the OpenShift Console, navigate to the OperatorHub by clicking **Operator** -> **Operator Hub** in the left side-pane.
 
 1. Search for "sail".
@@ -23,6 +25,46 @@ tbd
 1. Click **Operators** -> **Installed Operators** to verify that the sail-operator 
 is installed. `Succeeded` should appear in the **Status** column.
 
+#### Installing using the CLI
+
+*Prerequisites*
+
+* You have access to the cluster as a user with the `cluster-admin` cluster role.
+
+*Steps*
+
+1. Create the `openshift-operators` namespace (if it does not already exist).
+
+    ```bash
+    $ kubectl create namespace openshift-operators
+    ```
+
+1. Create the `Subscription` object with the desired `spec.channel`.
+
+    ```yaml
+    apiVersion: operators.coreos.com/v1alpha1
+    kind: Subscription
+    metadata:
+      name: sailoperator
+      namespace: openshift-operators
+    spec:
+      channel: "0.1-nightly"
+      installPlanApproval: Automatic
+      name: sailoperator
+      source: community-operators
+      sourceNamespace: openshift-marketplace
+    ```
+
+1. Verify that the installation succeeded by inspecting the CSV file.
+
+    ```bash
+    $ kubectl get csv -n openshift-operators
+    NAME                                     DISPLAY         VERSION                    REPLACES                                 PHASE
+    sailoperator.v0.1.0-nightly-2024-06-25   Sail Operator   0.1.0-nightly-2024-06-25   sailoperator.v0.1.0-nightly-2024-06-21   Succeeded
+    ```
+
+    `Succeeded` should appear in the sailoperator's `PHASE` column.
+
 ### Installation from Source
 
 If you're not using OpenShift or simply want to install from source, follow the [instructions in the Contributor Documentation](../README.md#deploying-the-operator).
@@ -36,8 +78,126 @@ The Sail-operator does not manage Gateways. You can deploy a gateway manually ei
 ## Multicluster
 tbd
 
-## Examples
-tbd
+## Addons
+
+Addons are managed separately from the Sail-operator. You can follow the [istio documentation](https://istio.io/latest/docs/ops/integrations/) for how to install addons. Below is an example of how to install some addons for Istio.
+
+The sample will deploy:
+
+- Prometheus
+- Jaeger
+- Kiali
+- Bookinfo demo app
+
+*Prerequisites*
+
+- Sail operator installed.
+- Control Plane installed with Sail.
+
+### Deploy Prometheus and Jaeger addons
+
+```sh
+kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/addons/prometheus.yaml
+kubectl apply -f https://raw.githubusercontent.com/istio/istio/master/samples/addons/jaeger.yaml
+```
+
+### Deploy Kiali addon
+
+Install the kiali operator.
+
+You can install the kiali operator through OLM if running on Openshift, otherwise you can use helm:
+
+```sh
+helm install --namespace kiali-operator --create-namespace kiali-operator kiali/kiali-operator
+```
+
+Find out the revision name of your Istio instance. In our case it is `test`.
+
+```bash
+$ kubectl get istiorevisions.operator.istio.io 
+NAME   READY   STATUS    IN USE   VERSION   AGE
+test True    Healthy   True     v1.21.0   119m
+```
+
+Create a Kiali resource and point it to your Istio instance. Make sure to replace `test` with your revision name in the fields `config_map_name`, `istio_sidecar_injector_config_map_name`, `istiod_deployment_name` and `url_service_version`.
+
+```sh
+kubectl apply -f - <<EOF
+apiVersion: kiali.io/v1alpha1
+kind: Kiali
+metadata:
+  name: kiali
+  namespace: istio-system
+spec:
+  external_services:
+    grafana:
+      enabled: false
+    istio:
+      component_status:
+        enabled: false
+      config_map_name: istio-test
+      istio_sidecar_injector_config_map_name: istio-sidecar-injector-test
+      istiod_deployment_name: istiod-test
+      url_service_version: 'http://istiod-test.istio-system:15014/version'
+EOF
+```
+
+### Deploy Gateway and Bookinfo
+
+Create the bookinfo namespace and enable injection.
+
+```sh
+kubectl get namespace bookinfo || kubectl create namespace bookinfo
+kubectl label namespace bookinfo istio.io/rev=test
+```
+
+Install Bookinfo demo app.
+
+```sh
+kubectl apply -n bookinfo -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/platform/kube/bookinfo.yaml
+kubectl apply -n bookinfo -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/platform/kube/bookinfo-versions.yaml
+```
+
+Install gateway API CRDs if they are not already installed.
+
+```sh
+kubectl get crd gateways.gateway.networking.k8s.io &> /dev/null || \
+  { kubectl kustomize "github.com/kubernetes-sigs/gateway-api/config/crd?ref=v1.1.0" | kubectl apply -f -; }
+```
+
+Create bookinfo gateway.
+
+```sh
+kubectl apply -n bookinfo -f https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/gateway-api/bookinfo-gateway.yaml
+kubectl wait -n bookinfo --for=condition=programmed gtw bookinfo-gateway
+```
+
+### Generate traffic and visualize your mesh
+
+Send traffic to the productpage service. Note that this command will run until cancelled.
+
+```sh
+export INGRESS_HOST=$(kubectl get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.status.addresses[0].value}')
+export INGRESS_PORT=$(kubectl get gtw bookinfo-gateway -n bookinfo -o jsonpath='{.spec.listeners[?(@.name=="http")].port}')
+export GATEWAY_URL=$INGRESS_HOST:$INGRESS_PORT
+watch curl http://${GATEWAY_URL}/productpage &> /dev/null
+```
+
+In a separate terminal, open Kiali to visualize your mesh.
+
+If using Openshift, open the Kiali route:
+
+```sh
+echo https://$(kubectl get routes -n istio-system kiali -o jsonpath='{.spec.host}')
+```
+
+Otherwise port forward to the kiali pod directly:
+
+```sh
+kubectl port-forward -n istio-system svc/kiali 20001:20001
+```
+
+You can view Kiali dashboard at: http://localhost:20001
 
 ## Observability Integrations
 

diff --git a/enhancements/README.md b/enhancements/README.md
@@ -0,0 +1 @@
+This directory stores all of our Sail Enhancement Proposal (SEP) documents in markdown format. For more information on the process around enhancements, see [SEP1-enhancement-process.md](./SEP1-enhancement-process.md). If you want to create a SEP, be sure to check out the [SEP template](./SEP0-template.md).
diff --git a/enhancements/SEP0-template.md b/enhancements/SEP0-template.md
@@ -0,0 +1,41 @@
+|Status                                             | Authors      | Created    | 
+|---------------------------------------------------|--------------|------------|
+|WIP/Proposed/Accepted/Declined/Implementation/Done | @dgn         | 2024-07-09 |
+
+# SEP Template
+
+## Overview
+Some short paragraphs on what the enhancement attempts to solve and why it's important.
+
+## Goals
+Itemized list of things you want to achieve. Can be functional/nonfunctional requirements.
+
+## Non-goals
+Itemized list of things specifically excluded from the design. Could be either to simplify the review or to avoid misunderstandings.
+
+## Design
+This is free-form; use as many or few sub-headings as appropriate. The following are just examples, use them only if they apply to your SEP.
+
+### User Stories
+
+### API Changes
+
+### Architecture
+
+### Performance Impact
+
+### Backward Compatibility
+
+### Kubernetes vs OpenShift vs Other Distributions
+
+## Alternatives Considered
+Other approaches that have been discussed and discarded during or before the creation of the SEP. Should include the reasons why they have not been chosen.
+
+## Implementation Plan
+In the beginning, this should give a rough overview of the work required to implement the SEP. Later on when the SEP has been accepted, this should list the epics that have been created to track the work.
+
+## Test Plan
+When and how can this be tested? We'll want to automate testing as much as possible, so we need to start about testability early.
+
+## Change History (only required when making changes after SEP has been accepted)
+* 2024-07-09 Fixed a typo
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		This directory stores all of our Sail Enhancement Proposal (SEP) documents in markdown format. For more information on the process around enhancements, see [SEP1-enhancement-process.md](./SEP1-enhancement-process.md). If you want to create a SEP, be sure to check out the [SEP template](./SEP0-template.md).