Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update contribution docs, include istio's bookinfo #354

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 45 additions & 15 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,42 +7,72 @@ We welcome contributions :)
Also refer to [Collaboration](./README.md) for communication channels.

## Setting up for local Development
* Clone the repo and set ADMIRAL_HOME env variable

### Pre-requisite

#### Pre requisite 1 - Setup environment variables
```bash
git clone https://github.com/istio-ecosystem/admiral.git
cd admiral
export ADMIRAL_HOME=$(pwd)
```
* 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
```

#### Pre requisite 2 - Create a kubernetes cluster
```bash
$ADMIRAL_HOME/tests/create_cluster.sh 1.16.8
$ADMIRAL_HOME/tests/create_cluster.sh 1.28.0
export KUBECONFIG=~/.kube/config
```
* 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.20.2 osx`
#### Pre requisite 3 - Install Istio
For Mac (Intel based):
```bash
$ADMIRAL_HOME/tests/install_istio.sh 1.20.2 osx
```

Mac (Apple Silicon):
```bash
$ADMIRAL_HOME/tests/install_istio.sh 1.20.2 osx-arm64
```

Linux:
```bash
$ADMIRAL_HOME/tests/install_istio.sh 1.20.2 linux
```

#### Pre requisite 4 - Config DNS Proxying
Configure DNS for service entries (hosts) ending in `global`, by enabling [Enable DNS proxy mode](https://istio.io/latest/docs/ops/configuration/traffic-management/dns-proxy/)

Mac (Apple Silicon): `$ADMIRAL_HOME/tests/install_istio.sh 1.20.2 osx-arm64`
#### Pre requisite 5 - Install kustomize
```bash
brew install kustomize
```

Linux: `$ADMIRAL_HOME/tests/install_istio.sh 1.20.2 linux`
## Running Admiral

* Set up necessary permissions and configurations for Admiral
### Install Admiral CRDs, and grant access using RBAC

```bash
$ADMIRAL_HOME/install/scripts/dev_setup.sh
```
* Run `admiral` from your IDE (assumes that the kubeconfig is for the cluster is at `~/.kube/config`)

### Installing istio's bookinfo applications
```bash
kubectl apply -f out/yaml/bookinfo/* --kubeconfig $KUBECONFIG
```
$ADMIRAL_HOME/admiral/cmd/admiral/main.go --kube_config "<Path_to_Kubeconfig>"

### Run admiral as a local process
```bash
go run $ADMIRAL_HOME/admiral/cmd/admiral/main.go --sync_period=5s --kube_config $KUBECONFIG
```

* `Optional`: Adding a second cluster for admiral to monitor (for multi-cluster)
## Optional configurations

### Multi cluster admiral setup
```bash
$ADMIRAL_HOME/install/scripts/cluster-secret.sh <Path_to_Kubeconfig_Admiral_Cluster> <Path_to_Kubeconfig_Remote_Cluster> admiral
```

* `Optional`: Run `admiral` inside the minikube cluster
### Running admiral as a deployment inside a kubernetes cluster
```bash
# point to the admiral primary cluster
export KUBECONFIG=<Path_to_Kubeconfig_Admiral_Cluster>
Expand All @@ -60,7 +90,7 @@ minikube service admiral-http -n admiral --url
minikube service admiral-metrics -n admiral --url
```

* `Optional`: Install prometheus for metrics.
### Install prometheus for metrics.
```bash
# build the yaml files
make gen-yaml
Expand Down
Loading