|
1 | | -# M3DB Operator [](https://buildkite.com/m3/m3db-operator) [](https://codecov.io/gh/m3db/m3db-operator) |
| 1 | +# M3 Operator [](https://buildkite.com/m3/m3db-operator) [](https://codecov.io/gh/m3db/m3db-operator) |
2 | 2 |
|
3 | | -The M3DB Operator is a project dedicated to setting up M3DB on Kubernetes. It aims to automate everyday tasks around managing M3DB. Specifically, it aims to automate: |
| 3 | +The M3 Operator helps you set up M3 on Kubernetes. It aims to automate everyday tasks around managing M3, specifically, it aims to automate: |
4 | 4 |
|
5 | | -* Creating M3DB clusters |
6 | | -* Destroying M3DB clusters |
7 | | -* Expanding clusters (adding instances) |
8 | | -* Shrinking clusters (removing instances) |
9 | | -* Replacing failed instances |
| 5 | +- Creating clusters |
| 6 | +- Destroying clusters |
| 7 | +- Expanding clusters (adding instances) |
| 8 | +- Shrinking clusters (removing instances) |
| 9 | +- Replacing failed instances |
10 | 10 |
|
11 | | -More information: |
| 11 | +## Table of Contents |
12 | 12 |
|
13 | | -- [Documentation][docs] |
14 | | -- [Gitter room](https://gitter.im/m3db/kubernetes) |
15 | | -- [M3DB Google Group](https://groups.google.com/forum/#!forum/m3db) |
| 13 | +- [M3 Operator  [](https://codecov.io/gh/m3db/m3db-operator)](#m3-operator--) |
| 14 | + - [Table of Contents](#table-of-contents) |
| 15 | + - [More Information](#more-information) |
| 16 | + - [Community Meetings](#community-meetings) |
| 17 | + - [Office Hours](#office-hours) |
| 18 | + - [Install](#install) |
| 19 | + - [Dependencies](#dependencies) |
| 20 | + - [Usage](#usage) |
| 21 | + - [Create an etcd Cluster](#create-an-etcd-cluster) |
| 22 | + - [Install the Operator](#install-the-operator) |
| 23 | + - [Create an M3 Cluster](#create-an-m3-cluster) |
| 24 | + - [Resize a Cluster](#resize-a-cluster) |
| 25 | + - [Delete a Cluster](#delete-a-cluster) |
| 26 | + - [Contributing](#contributing) |
16 | 27 |
|
17 | | -## Getting Started |
| 28 | +## More Information |
18 | 29 |
|
19 | | -The following instructions serve as a quickstart to get an M3DB cluster up and running in your Kubernetes cluster. This |
20 | | -setup is not for production use, as there's no persistent storage. More information on production-grade clusters can be |
21 | | -found in our [docs][docs]. |
| 30 | +- [Documentation](https://m3db.io/docs/operator/) |
| 31 | +- [Slack](http://bit.ly/m3slack) |
| 32 | +- [Forum (Google Group)](https://groups.google.com/forum/#!forum/m3db) |
22 | 33 |
|
23 | | -### Kubernetes Cluster Prerequisites |
| 34 | +### Community Meetings |
24 | 35 |
|
25 | | -The M3DB operator targets Kubernetes **1.11** and **1.12**. We generally aim to target the latest two minor versions |
26 | | -supported by GKE but welcome community contributions to support more versions! |
| 36 | +M3 contributors and maintainers have regular meetings. Join our M3 meetup group to receive notifications on upcoming meetings: <https://www.meetup.com/M3-Community/>. |
27 | 37 |
|
28 | | -The M3DB operator is intended for creating highly available clusters across distinct failure domains. For this reason we |
29 | | -currently only support Kubernetes clusters with nodes in at least 3 zones, but [support][zonal] for zonal clusters is |
30 | | -coming soon. |
| 38 | +You can find recordings of past meetups here: <https://vimeo.com/user/120001164/folder/2290331>. |
31 | 39 |
|
32 | | -When running on GKE, the user applying the manifests will need the ability to allow `cluster-admin-binding` during the |
33 | | -installation. Use the following `ClusterRoleBinding` with the user name provided by gcloud: |
| 40 | +### Office Hours |
34 | 41 |
|
35 | | -``` |
36 | | -kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud config get-value core/account) |
37 | | -``` |
| 42 | +Members of the M3 team hold office hours on the third Thursday of every month from 11-1pm EST. To join, make sure to sign up for a slot here: <https://calendly.com/chronosphere-intro/m3-community-office-hours>. |
38 | 43 |
|
39 | | -### Installing the M3DB Operator |
| 44 | +## Install |
40 | 45 |
|
41 | | -With Helm: |
| 46 | +### Dependencies |
42 | 47 |
|
43 | | -``` |
44 | | -helm repo add m3db https://m3-helm-charts.storage.googleapis.com/stable |
45 | | -helm install m3db/m3db-operator --namespace m3db-operator |
46 | | -``` |
| 48 | +The M3 operator targets Kubernetes **1.11** and **1.12**. We aim to target the latest two minor versions supported by GKE but welcome community contributions to support more versions |
47 | 49 |
|
48 | | -With `kubectl` (will install in the `default` namespace): |
| 50 | +The M3 operator is intended for creating highly available clusters across distinct failure domains. For this reason it only support Kubernetes clusters with nodes **in at least 3 zones**, but [support][https://github.com/m3db/m3db-operator/issues/68] for zonal clusters is coming soon. |
49 | 51 |
|
50 | | -``` |
51 | | -kubectl apply -f https://raw.githubusercontent.com/m3db/m3db-operator/v0.13.0/bundle.yaml |
52 | | -``` |
| 52 | +## Usage |
53 | 53 |
|
54 | | -## Managing Clusters |
| 54 | +The following instructions are a quickstart to get a cluster up and running. This setup is not for production use, as it has no persistent storage. [Read the operator documentation](https://m3db.io/docs/operator/) for more information on production-grade clusters. |
55 | 55 |
|
56 | | -### Creating a Cluster |
| 56 | +### Create an etcd Cluster |
57 | 57 |
|
58 | | -Create a simple etcd cluster to store M3DB's topology: |
| 58 | +M3 stores its cluster placements and runtime metadata in [etcd](https://etcd.io/) and needs a running cluster to communicate with. |
59 | 59 |
|
60 | | -``` |
| 60 | +```shell |
61 | 61 | kubectl apply -f https://raw.githubusercontent.com/m3db/m3db-operator/v0.13.0/example/etcd/etcd-basic.yaml |
62 | 62 | ``` |
63 | 63 |
|
64 | | -Apply manifest with your zones specified for isolation groups: |
65 | | - |
66 | | -```yaml |
67 | | -apiVersion: operator.m3db.io/v1alpha1 |
68 | | -kind: M3DBCluster |
69 | | -metadata: |
70 | | - name: simple-cluster |
71 | | -spec: |
72 | | - image: quay.io/m3db/m3dbnode:latest |
73 | | - replicationFactor: 3 |
74 | | - numberOfShards: 256 |
75 | | - # Default endpoints if using provided etcd manifests. |
76 | | - etcdEndpoints: |
77 | | - - http://etcd-0.etcd:2379 |
78 | | - - http://etcd-1.etcd:2379 |
79 | | - - http://etcd-2.etcd:2379 |
80 | | - isolationGroups: |
81 | | - - name: group1 |
82 | | - numInstances: 1 |
83 | | - nodeAffinityTerms: |
84 | | - - key: failure-domain.beta.kubernetes.io/zone |
85 | | - values: |
86 | | - - <zone-a> |
87 | | - - name: group2 |
88 | | - numInstances: 1 |
89 | | - nodeAffinityTerms: |
90 | | - - key: failure-domain.beta.kubernetes.io/zone |
91 | | - values: |
92 | | - - <zone-b> |
93 | | - - name: group3 |
94 | | - numInstances: 1 |
95 | | - nodeAffinityTerms: |
96 | | - - key: failure-domain.beta.kubernetes.io/zone |
97 | | - values: |
98 | | - - <zone-c> |
99 | | - podIdentityConfig: |
100 | | - sources: [] |
101 | | - namespaces: |
102 | | - - name: metrics-10s:2d |
103 | | - preset: 10s:2d |
104 | | - dataDirVolumeClaimTemplate: |
105 | | - metadata: |
106 | | - name: m3db-data |
107 | | - spec: |
108 | | - accessModes: |
109 | | - - ReadWriteOnce |
110 | | - resources: |
111 | | - requests: |
112 | | - storage: 100Gi |
| 64 | +### Install the Operator |
| 65 | + |
| 66 | +Using `kubectl` (installs in the `default` namespace): |
| 67 | + |
| 68 | +```shell |
| 69 | +kubectl apply -f https://raw.githubusercontent.com/m3db/m3db-operator/v0.13.0/bundle.yaml |
113 | 70 | ``` |
114 | 71 |
|
115 | | -### Resizing a Cluster |
| 72 | +### Create an M3 Cluster |
116 | 73 |
|
117 | | -To resize a cluster, specify the new number of instances you want in each zone either by reapplying your manifest or |
118 | | -using `kubectl edit`. The operator will safely scale up or scale down your cluster. |
| 74 | +The following creates an M3 cluster with 3 replicas of data across 256 shards that connects to the 3 available etcd endpoints. |
119 | 75 |
|
120 | | -### Deleting a Cluster |
| 76 | +```shell |
| 77 | +kubectl apply -f https://raw.githubusercontent.com/m3db/m3db-operator/master/example/m3db-local.yaml |
| 78 | +``` |
121 | 79 |
|
122 | | -Delete a cluster using `kubectl delete`. You will to remove the etcd data as well, or wipe the data generated by the |
123 | | -operator if you intend to reuse the etcd cluster for another M3DB cluster: |
| 80 | +When running on GKE, the user applying the manifests needs the ability to allow `cluster-admin-binding` during installation. Use the following `ClusterRoleBinding` with the user name provided by gcloud: |
124 | 81 |
|
| 82 | +```shell |
| 83 | +kubectl create clusterrolebinding cluster-admin-binding --clusterrole=cluster-admin --user=$(gcloud config get-value core/account) |
125 | 84 | ``` |
| 85 | + |
| 86 | +### Resize a Cluster |
| 87 | + |
| 88 | +To resize a cluster, specify the new number of instances you want in each zone either by reapplying your manifest or using `kubectl edit`. The operator safely scales up or scales down the cluster. |
| 89 | + |
| 90 | +### Delete a Cluster |
| 91 | + |
| 92 | +```shell |
| 93 | +kubectl delete m3dbcluster simple-cluster |
| 94 | +``` |
| 95 | + |
| 96 | +You also need to remove the etcd data, or wipe the data generated by the operator if you intend to reuse the etcd cluster for another M3 cluster: |
| 97 | + |
| 98 | +```shell |
126 | 99 | kubectl exec etcd-0 -- env ETCDCTL_API=3 etcdctl del --keys-only --prefix "" |
127 | 100 | ``` |
128 | 101 |
|
129 | 102 | ## Contributing |
130 | 103 |
|
131 | | -We welcome community contributions to to the M3DB operator! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more |
132 | | -information. Please note that on creating a pull request you will be asked to agree to the Uber CLA before we can accept |
133 | | -your contribution. |
| 104 | +You can ask questions and give feedback in the following ways: |
| 105 | + |
| 106 | +- [Create a GitHub issue](https://github.com/m3db/m3db-operator/issues) |
| 107 | +- [In the public M3 Slack](http://bit.ly/m3slack) |
| 108 | +- [In the M3 forum (Google Group)](https://groups.google.com/forum/#!forum/m3db) |
| 109 | + |
| 110 | +The M3 operator welcomes pull requests, read [the development guide](CONTRIBUTING.md) to help you get setup for building and contributing. |
134 | 111 |
|
135 | | -## License |
136 | | -This project is licensed under the Apache license -- see the [LICENSE](https://github.com/m3db/m3db-operator/blob/master/LICENSE) file for details. |
| 112 | +* * * |
137 | 113 |
|
138 | | -[docs]: https://operator.m3db.io/ |
139 | | -[zonal]: https://github.com/m3db/m3db-operator/issues/68 |
| 114 | +This project is released under the [Apache License, Version 2.0](https://github.com/m3db/m3/blob/master/LICENSE). |
0 commit comments