Skip to content

Commit 244116f

Browse files
committed
Updated documentation and Helm parameters to reflect name changes.
Signed-off-by: Diana Arroyo <darroyo@us.ibm.com>
1 parent 8fed3ae commit 244116f

File tree

5 files changed

+211
-115
lines changed

5 files changed

+211
-115
lines changed

README.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
Multi-Cluster Application Dispatcher
22
==
33

4-
The `multi-cluster-app-dispatcher` is a Kubernetes controller providing mechanisms for applications to manage batch jobs.
4+
The `multi-cluster-app-dispatcher` is a Kubernetes controller providing mechanisms for applications to manage batch jobs in a single or mult-cluster environment.
55

6-
`multi-cluster-app-dispatcher` is capable of (i) providing an abstraction for wrapping all resources of the job/application and treating them holistically, (ii) queuing job/application creation requests and applying different queuing policies, e.g., FIFO, Priority, (iii) dispatching the job to one of multiple clusters, where a queuing agent runs, using configurable dispatch policies, and (iv) auto-scaling pod sets, balancing job demands and cluster availability (future work).
6+
The `multi-cluster-app-dispatcher` (`MCAD`) controller is capable of (i) providing an abstraction for wrapping all resources of the job/application and treating them holistically, (ii) queuing job/application creation requests and applying different queuing policies, e.g., First In First Out, Priority, (iii) dispatching the job to one of multiple clusters, where a `MCAD` queuing agent runs, using configurable dispatch policies, and (iv) auto-scaling pod sets, balancing job demands and cluster availability (future work).
77

88

99
## Build Information
1010

11-
Follow the build instructions [here](./doc/build/build.md) to build the Multi-Cluster-App-Dispatcher controller.
11+
Follow the [build instructions here](./doc/build/build.md) to build the Multi-Cluster-App-Dispatcher controller.
1212

1313
## Deployment Information
1414

15-
Refer to [deployment](./doc/deploy/deployment.md) on how to deploy the `multi-cluster-app-dispatcher` as a controller in Kubernetes.
15+
Refer to [deployment instructions here](./doc/deploy/deployment.md) on how to deploy the `multi-cluster-app-dispatcher` as a controller in Kubernetes.
1616

1717
## Tutorial
1818

deployment/kube-arbitrator/values.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ deploymentName: xqueuejob-controller
55
namespace: kube-system
66
replicaCount: 1
77
image:
8-
repository: registry.stage1.ng.bluemix.net/ibm/kube-arbitrator
8+
repository: mcad-controller
99
tag: latest
1010
pullPolicy: Always
1111
resources:

doc/build/build.md

+17-9
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
1-
# Multi-Cluster-App-Deployer Controller Build Instructions
1+
# Multi-Cluster-App-Dispatcher Controller Build Instructions
22

3-
This document will show how to build the `Multi-Cluster-App-Deployer` Kubernetes Controller that operates on an AppWrapper kubernetes custom resource definition. It is for [master](https://github.com/IBM/multi-cluster-app-dispatcher/tree/master) branch.
3+
This document will show how to build the `Multi-Cluster-App-Deployer` (`MCAD`) Kubernetes Controller that operates on an `AppWrapper` kubernetes custom resource definition. Instructions are for the [master](https://github.com/IBM/multi-cluster-app-dispatcher/tree/master) branch.
44

55
## 1. Pre-condition
66

77
### Docker Environment
88

9-
To build `Multi-Cluster-App-Deployer`, a running Docker env. must be available. Here is a document on [Getting Started with Docker](https://www.docker.com/get-started).
9+
To build `Multi-Cluster-App-Deployer`, a running Docker environment must be available. Here is a document on [Getting Started with Docker](https://www.docker.com/get-started).
1010

1111
### Clone Multi-Cluster-App-Deployer Git Repo
1212

@@ -20,22 +20,22 @@ Checking out files: 100% (####/####), done.
2020
$
2121
```
2222

23-
## 2. Building the Multi-Cluster-App-Deployer Controller
23+
## 2. Building the Multi-Cluster-App-Deployer Controller
2424

25-
### Build the Executables
25+
### Build the Executable
2626

2727
Run the build script `build.sh`:
2828
```
2929
$ cd multi-cluster-app-dispatcher/deployment/
3030
31-
$ ./build.sh
31+
$ ./build.sh
3232
...
3333
+ cd ..
3434
+ make generate-code
3535
Compiling deepcopy-gen
3636
Generating deepcopy
3737
go build -o _output/bin/deepcopy-gen ./cmd/deepcopy-gen/
38-
_output/bin/deepcopy-gen -i ./pkg/apis/controller/v1alpha1/ -O zz_generated.deepcopy
38+
_output/bin/deepcopy-gen -i ./pkg/apis/controller/v1alpha1/ -O zz_generated.deepcopy
3939
+ make kar-controller
4040
mkdir -p _output/bin
4141
CGO_ENABLED=0 GOARCH=amd64 go build -o _output/bin/kar-controllers ./cmd/kar-controllers/
@@ -49,9 +49,9 @@ deepcopy-gen kar-controllers
4949
$
5050
```
5151

52-
### Build the Multi-Cluster-App-Dispatcher
52+
### Build the Multi-Cluster-App-Dispatcher Image
5353

54-
Run the image build scfript `image.sh`:
54+
Run the image build script `image.sh`:
5555

5656
```
5757
$ ./image.sh
@@ -80,3 +80,11 @@ REPOSITORY TAG IMAGE ID CREATED
8080
mcad-controller deleteme 1dbf126976cf 11 minutes ago 272MB
8181
$
8282
```
83+
### Push the Multi-Cluster-App-Dispatcher Image to a Image Repository
84+
The following example assumes an available `<repository>/mcad-controller` on [Docker Hub](https://hub.docker.com)
85+
```
86+
$ docker login
87+
$ docker push <respository>/mcad-controller:v1.14
88+
```
89+
90+
Refer to [deployment](../deploy/deployment.md) on how to deploy the `multi-cluster-app-dispatcher` as a controller in Kubernetes.

doc/deploy/deployment.md

+15-12
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# Deploying Multi-Cluster-App-Wrapper Controller
2-
Follow the instructions below to deploy the __Multi-Cluster Application Wrapper__ (_MCAD_) controller in an existing Kubernetes cluster:
2+
Follow the instructions below to deploy the __Multi-Cluster Application Dispatcher__ (_MCAD_) controller in an existing Kubernetes cluster:
33

44
## Pre-Reqs
55
### - Cluster running Kubernetes v1.10 or higher.
@@ -23,7 +23,7 @@ helm list
2323
Follow the build instructions [here](../build/build.md) to build the `multi-cluster-app-dispatcher` controller docker image and push the image to a docker registry.
2424

2525

26-
### Determine if the cluster has enough resources for installing the Helm chart for the Multi-Cluster-App-Dispatcher.
26+
### Determine Resources for Installing the Helm Chart for the Multi-Cluster-App-Dispatcher.
2727

2828
The default memory resource demand for the `multi-cluster-app-dispatcher` controller is `2G`. If your cluster is a small installation such as MiniKube you will want to adjust the Helm installation resource requests accordingly.
2929

@@ -74,7 +74,7 @@ Allocated resources:
7474
Events: <none>
7575
7676
```
77-
In the example above, there is only one node (`minikube`) in the cluster with the majority of the cluster memory used (`1,254Mi` used out of `1,936Mi` allocatable capacity) leaving less than `700Mi` available capacity for new pod deployments in the cluster. Since the default memory demand for the <em>Multi-Cluster Application Dispatcher</em> controller pod is `2G` the cluster has insufficient memory to deploy the controller. Instruction notes provided below show how to override the defaults according to the available capacity in your cluster.
77+
In the example above, there is only one node (`minikube`) in the cluster with the majority of the cluster memory used (`1,254Mi` used out of `1,936Mi` allocatable capacity) leaving less than `700Mi` available capacity for new pod deployments in the cluster. Since the default memory demand for the <em>Multi-Cluster Application Dispatcher</em> controller pod is `2G` the cluster has __insufficient__ memory to deploy the controller. Instruction notes provided below show how to override the defaults according to the available capacity in your cluster.
7878

7979
## Installation Instructions
8080
### 1. Download the github project.
@@ -89,7 +89,7 @@ or
8989
```
9090
git clone git@github.com:IBM/multi-cluster-app-dispatcher.git
9191
```
92-
### 2. Navigate to the Helm deployment directory.
92+
### 2. Navigate to the Helm Deployment Directory.
9393
```
9494
cd multi-cluster-app-wrapper/deployment
9595
```
@@ -98,7 +98,7 @@ cd multi-cluster-app-wrapper/deployment
9898
Install the __Multi-Cluster-App-Dispatcher Controller__ using the commands below. The `--wait` parameter in the Helm command below is used to ensure all pods of the helm chart are running and will not return unless the default timeout expires (*typically 300 seconds*) or all the pods are in `Running` state.
9999

100100

101-
Before submitting the command below you should ensure you have enough resources in your cluster to deploy the helm chart (*see Pre-Reqs section above*). If you do not have enough compute resources in your cluster you can adjust the resource request via the command line. See an example below.
101+
Before submitting the command below you should ensure you have enough resources in your cluster to deploy the helm chart (*see __Pre-Reqs__ section above*). If you do not have enough compute resources in your cluster to run with the default allocation, you can adjust the resource request via the command line by using the optional parameters `--resources.*.*`. See an example [*Example 3*](#example-3) in section __3.a)__ below.
102102

103103
All Helm parameters are described in the table at the bottom of this section.
104104
#### 3.a) Start the Multi-Cluster-App-Dispatcher Controller on All Target Deployment Clusters (*Agent Mode*).
@@ -107,18 +107,21 @@ __Agent Mode__: Install and set up the `multi-cluster-app-dispatcher` controller
107107
helm install kube-arbitrator --namespace kube-system --wait --set image.repository=<image repository and name> --set image.tag=<image tag> --set imagePullSecret.name=<Name of image pull kubernetes secret> --set imagePullSecret.password=<REPLACE_WITH_REGISTRY_TOKEN_GENERATED_IN_PREREQs_STAGE1_REGISTRY.d)> --set localConfigName=<Local Kubernetes Config File for Current Cluster> --set volumes.hostPath=<Host_Path_location_of_local_Kubernetes_config_file>
108108
```
109109

110-
For example (*Assuming the default for `image.repository`, `image.tag`*):
110+
##### Example 1
111+
*Assuming the default for `image.repository` and `image.tag` fields*:
111112
```
112113
helm install kube-arbitrator --namespace kube-system
113114
```
114-
or
115+
##### Example 2
116+
*Assuming the MCAD controller image is already pulled onto the local target machine with the following image `image.repository=mcad-controller`, `image.tag=latest`*
115117
```
116-
helm install kube-arbitrator --namespace kube-system --wait --set imagePullSecret.name=mcad-controller-registry-secret --set imagePullSecret.password=eyJhbGc...y8gJNcpnipUu0 --set image.pullPolicy=Always --set localConfigName=config_110 --set volumes.hostPath=/etc/kubernetes
118+
helm install kube-arbitrator --namespace kube-system --wait --set image.pullPolicy=Never --set image.repository=mcad-controller --set image.tag=latest
117119
```
118-
NOTE: You can adjust the cpu and memory demands of the deployment with command line overrides. For example:
120+
##### Example 3
121+
To adjust the cpu and memory demands of the deployment with command line overrides example:
119122

120123
```
121-
helm install kube-arbitrator --namespace kube-system --wait -set resources.requests.cpu=1000m --set resources.requests.memory=1024Mi --set resources.limits.cpu=1000m --set resources.limits.memory=1024Mi --set image.repository=myDockerReegistry/mcad-controller --set image.tag=v1.11 --set image.pullPolicy=Always
124+
helm install kube-arbitrator --namespace kube-system --wait --set resources.requests.cpu=1000m --set resources.requests.memory=1024Mi --set resources.limits.cpu=1000m --set resources.limits.memory=1024Mi --set image.repository=myDockerReegistry/mcad-controller --set image.tag=latest --set image.pullPolicy=Always
122125
```
123126
#### 3.b) Start the Multi-Cluster-App-Dispatcher Controller on the Controller Cluster (*Dispatcher Mode*).
124127
_Dispatcher Mode__: Install and set up the Multi-Cluster-App-Dispatcher Controler (_MCAD_) in *Dispatcher Mode* for the control cluster that will dispatch the _MCAD_ controller to an *Agent* cluster using Helm.
@@ -160,7 +163,7 @@ The following table lists the configurable parameters of the helm chart and thei
160163
| `volumes.hostPath` | Full path on the host location where the `localConfigName` file is stored | | `/etc/kubernetes` |
161164

162165

163-
### 5. Verify the installation.
166+
### 4. Verify the installation.
164167
List the Helm installation. The `STATUS` should be `DEPLOYED`.
165168

166169
NOTE: The `--wait` parameter in the helm installation command from *step #3* above ensures all resources are deployed and running if the `STATUS` indicates `DEPLOYED`. Installing the Helm Chart without the `--wait` parameter does not ensure all resources are successfully running but may still show a `Status` of `Deployed`.
@@ -180,7 +183,7 @@ kubectl get appwrappers
180183

181184
Since no `appwrapper` jobs have yet to be deployed into the current cluster you should receive a message indicating `No resources found` for `appwrappers` but your cluster now has _MCAD_ controller enabled. Use the [tutorial](../doc/usage/tutorial.md) to deploy an example `appwrapper` job.
182185

183-
### 6. Remove the Multi-Cluster-App-Dispatcher Controller from your cluster.
186+
### 5. Remove the Multi-Cluster-App-Dispatcher Controller from your cluster.
184187

185188
List the deployed Helm charts and identify the name of the Multi-Cluster-App-Dispatcher Controller installation.
186189
```bash

0 commit comments

Comments
 (0)