diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3fb5f385..0de0f871 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,13 +13,20 @@ git clone https://github.com/istio-ecosystem/admiral.git cd admiral export ADMIRAL_HOME=$(pwd) ``` -* Run a k8s cluster using [minikube](https://kubernetes.io/docs/setup/learning-environment/minikube/) (you can use any k8s cluster if one exists already) +* Run a [minikube](https://kubernetes.io/docs/setup/learning-environment/minikube/) k8s cluster using existing script (you can use any k8s cluster if one exists already) +* Note: Recommend using k8s version 1.16.8 or above to work with recent istio version ```bash -minikube start --memory=8192 --cpus=4 --kubernetes-version=v1.14.2 +$ADMIRAL_HOME/tests/create_cluster.sh 1.16.8 export KUBECONFIG=~/.kube/config ``` -* Install [Prerequisites](./docs/Examples.md#Prerequisite) +* Install [Prerequisites](./docs/Examples.md#Prerequisite) and make sure to install istio control plane in cluster. Alternatively, you can use the script to install istio control plane on the cluster created in previous step: + +Mac: `$ADMIRAL_HOME/tests/install_istio.sh 1.7.4 osx` + +Linux: `$ADMIRAL_HOME/tests/install_istio.sh 1.7.4 linux` + * Set up necessary permissions and configurations for Admiral + ```bash $ADMIRAL_HOME/install/scripts/dev_setup.sh ``` diff --git a/docs/Admiral_Diagram.png b/docs/Admiral_Diagram.png new file mode 100644 index 00000000..537e4c1b Binary files /dev/null and b/docs/Admiral_Diagram.png differ diff --git a/docs/Examples.md b/docs/Examples.md index 50e5daa3..267b56bc 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -18,6 +18,79 @@ Delete Istio's envoy filter for translating `global` to `svc.cluster.local` at i ## Example Installations & Demos +### Production Deployment + +![](Admiral_Diagram.png) + + +An admiral production set up would have two types of clusters: +- cluster where admiral runs called the `main` cluster +- clusters which admiral watches, monitors and creates Istio CRs called the `remote` clusters + +The requirements are different for the two types: +- admiral namespace will exist in the main cluster +- admiral-sync namespace will exist in remote clusters that admiral watches and monitors. + +1\. Set necessary environment variables + +The following steps show how you can install admiral in the main cluster and then provision secrets for it to watch the remote clusters. + +``` +While the process shown below using shell scripts is manual, automation can be built for +i) installing admiral and its necessary resources (using a CD pipeline) +ii) Provisioning secret for every new cluster created or upgraded as a post cluster create step +``` + +```bash +# Set main cluster env variable +export MAIN_CLUSTER= + +# Set remote cluster env variable +export REMOTE_CLUSTER= +``` + +2\. Install/Run Admiral in the main cluster + +```bash +#Download and extract admiral + +wget https://github.com/istio-ecosystem/admiral/releases/download/v1.0/admiral-install-v1.0.tar.gz +tar xvf admiral-install-v1.0.tar.gz + +export ADMIRAL_HOME=./admiral-install-v1.0 +``` + +```bash +#Install admiral +export KUBECONFIG=$MAIN_CLUSTER +$ADMIRAL_HOME/scripts/install_admiral.sh $ADMIRAL_HOME + +``` + +3\. Add main cluster to Admiral's watcher + +Since there are most likely other workloads running in the same cluster where admiral lives, admiral needs to watch the cluster it's currently living in as well. This step can be skipped if Admiral runs in a dedicated cluster. +Let admiral monitor the cluster it lives in by using the secret to talk to the API server of the cluster where it runs. + +``` +$ADMIRAL_HOME/scripts/cluster-secret.sh $MAIN_CLUSTER $MAIN_CLUSTER admiral +``` + +4\. Install/Run Admiral-Sync in the remote clusters that admiral monitors +``` +# Create admiral role and bindings on remote cluster +kubectl apply --context=$REMOTE_CLUSTER -f $ADMIRAL_HOME/yaml/remotecluster.yaml +``` +5\. Add Remote Cluster to Admiral's watcher +``` +# Create the k8s secret for admiral to monitor remote cluster. +$ADMIRAL_HOME/scripts/cluster-secret.sh $MAIN_CLUSTER $REMOTE_CLUSTER admiral +``` + +At this point, admiral is watching `remote cluster` + +`Repeat steps 4 and 5 to add another remote cluster to be watched by Admiral.` + ### Single cluster #### Install/Run Admiral