updated readme
This commit is contained in:
parent
4ebb402015
commit
3a85e44ad4
267
README.md
267
README.md
@ -1,100 +1,240 @@
|
||||
# kubernetes-operator
|
||||
// TODO(user): Add simple overview of use/purpose
|
||||
# ServerManager Kubernetes Operator
|
||||
|
||||
A kubernetes operator used to manage servers using CRDs
|
||||
|
||||
## Description
|
||||
// TODO(user): An in-depth paragraph about your project and overview of use
|
||||
|
||||
## Getting Started
|
||||
This is a kubernetes operator used to manage game servers and is used in the implementation of the kubernetes instance manager in the [ServerManager backend](https://git.acooldomain.co/server-manager/backend)
|
||||
|
||||
### Prerequisites
|
||||
- go version v1.22.0+
|
||||
- docker version 17.03+.
|
||||
- kubectl version v1.11.3+.
|
||||
- Access to a Kubernetes v1.11.3+ cluster.
|
||||
## Important
|
||||
|
||||
### To Deploy on the cluster
|
||||
**Build and push your image to the location specified by `IMG`:**
|
||||
Currently the only supported ingress is traefik using the `IngressRoute` CRD
|
||||
|
||||
## Adding ServerManager operator to your cluster
|
||||
|
||||
### Install the CRDs
|
||||
|
||||
To install the CRDs you must first clone this repository using:
|
||||
|
||||
```sh
|
||||
make docker-build docker-push IMG=<some-registry>/kubernetes-operator:tag
|
||||
git clone https://git.acooldomain.co/server-manager/kubernetes-operator servermanager-operator
|
||||
cd servermanager-operator
|
||||
```
|
||||
|
||||
**NOTE:** This image ought to be published in the personal registry you specified.
|
||||
And it is required to have access to pull the image from the working environment.
|
||||
Make sure you have the proper permission to the registry if the above commands don’t work.
|
||||
|
||||
**Install the CRDs into the cluster:**
|
||||
After the repository is cloned to install the CRDs just apply them using:
|
||||
|
||||
```sh
|
||||
make install
|
||||
kubectl -f config/crd
|
||||
```
|
||||
|
||||
**Deploy the Manager to the cluster with the image specified by `IMG`:**
|
||||
### Setting up the ServerManager Operator
|
||||
|
||||
#### Configuration
|
||||
|
||||
The server-manager operator takes a configuration file called config.yaml and expects to find it in the same namespace under the name `server-manager-config` with a key named `config.yaml` containing a yaml file in the following schema
|
||||
|
||||
```yaml
|
||||
domain_label: string
|
||||
default_domain: string
|
||||
browser:
|
||||
domain: string
|
||||
sub_path: string
|
||||
auth_header: string
|
||||
cert_resolver: string
|
||||
entrypoints:
|
||||
- string
|
||||
|
||||
additional_routes:
|
||||
- IngressRouteRoute
|
||||
|
||||
middleware:
|
||||
name: string
|
||||
namespace: string
|
||||
```
|
||||
|
||||
#### Configuration values
|
||||
|
||||
> **domain_label**
|
||||
> optional
|
||||
> type: string
|
||||
> description: The name of a label on the node that it's value is a DNS record that points to that node.
|
||||
|
||||
> **default_domain**
|
||||
> type: string
|
||||
> description: The domain to use if the label in `domain_label` is not present on the node the pod runs on
|
||||
|
||||
> **browser.domain**
|
||||
> type: string
|
||||
> description: The domain that all file browsers would run on
|
||||
|
||||
> **browser.sub_path**
|
||||
> type: string
|
||||
> description: A path prefix that all browsers will run under
|
||||
|
||||
> **browser.auth_header**
|
||||
> type: string
|
||||
> description: The header used to identify a user on the browser container
|
||||
|
||||
> **browser.additional_routes**
|
||||
> type: IngressRouteRoute
|
||||
> description: Any additional routes that would point to anything other than the browser, usually needed for some forwardAuth middlewares
|
||||
|
||||
> **browser.middleware**
|
||||
> type: MiddlewareRef
|
||||
> description: A reference to the middleware that will handle authentication for the browsers
|
||||
|
||||
#### Example configuration
|
||||
|
||||
An example configuration that is close to what is used in [ServerManager](https://games.acooldomain.co)
|
||||
|
||||
```yaml
|
||||
domain_label: "ddns.acooldomain.co/hostname"
|
||||
default_domain: "acooldomain.co"
|
||||
browser:
|
||||
domain: games.acooldomain.co
|
||||
sub_path: /browsers
|
||||
auth_header: x-authentik-username
|
||||
cert_resolver: letsencrypt
|
||||
entrypoints:
|
||||
- websecure
|
||||
|
||||
additional_routes: # This additional route is required for the Authentik middleware
|
||||
- kind: Rule
|
||||
match: "Host(`games.acooldomain.co`) && PathPrefix(`/outpost.goauthentik.io/`)"
|
||||
priority: 15
|
||||
services:
|
||||
- kind: Service
|
||||
name: ak-outpost-traefik
|
||||
namespace: authentik
|
||||
port: 9000
|
||||
|
||||
middleware:
|
||||
name: authentik
|
||||
namespace: authentik
|
||||
```
|
||||
|
||||
And in a `ConfigMap` it looks as follows (replace `<namespace>` with the desired namespace):
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: ConfigMap
|
||||
metadata:
|
||||
name: server-manager-config
|
||||
namespace: <namespace>
|
||||
data:
|
||||
config.yaml: |
|
||||
domain_label: "ddns.acooldomain.co/hostname"
|
||||
default_domain: "acooldomain.co"
|
||||
browser:
|
||||
domain: games.acooldomain.co
|
||||
sub_path: /browsers
|
||||
auth_header: x-authentik-username
|
||||
cert_resolver: letsencrypt
|
||||
entrypoints:
|
||||
- websecure
|
||||
|
||||
additional_routes:
|
||||
- kind: Rule
|
||||
match: "Host(`games.acooldomain.co`) && PathPrefix(`/outpost.goauthentik.io/`)"
|
||||
priority: 15
|
||||
services:
|
||||
- kind: Service
|
||||
name: ak-outpost-traefik
|
||||
namespace: authentik
|
||||
port: 9000
|
||||
|
||||
middleware:
|
||||
name: authentik
|
||||
namespace: authentik
|
||||
|
||||
```
|
||||
|
||||
### Roles
|
||||
|
||||
The servermanager-operator requires permissions to **modify/create/delete** `pods`, `pvcs`, `services`, and `ingressroutes.traefik.io` to allow full functionality
|
||||
to create a service account with these permissions run the following commands where `<namespace>` is the namespace the operator would be deployed to
|
||||
|
||||
```sh
|
||||
make deploy IMG=<some-registry>/kubernetes-operator:tag
|
||||
kubectl apply -n <namespace> -f https://git.acooldomain.co/server-manager/kubernetes-operator/raw/branch/main/config/rbac/service-account.yaml
|
||||
kubectl apply -n <namespace> -f https://git.acooldomain.co/server-manager/kubernetes-operator/raw/branch/main/config/rbac/role.yaml
|
||||
kubectl apply -n <namespace> -f https://git.acooldomain.co/server-manager/kubernetes-operator/raw/branch/main/config/rbac/role-binding.yaml
|
||||
```
|
||||
|
||||
> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
|
||||
privileges or be logged in as admin.
|
||||
### Manager
|
||||
|
||||
**Create instances of your solution**
|
||||
You can apply the samples (examples) from the config/sample:
|
||||
To install the operator itself after all the setup is complete simply run:
|
||||
|
||||
```sh
|
||||
kubectl apply -k config/samples/
|
||||
kubectl apply -n <namespace> -f https://git.acooldomain.co/server-manager/kubernetes-operator/raw/branch/main/config/manager/manager.yaml
|
||||
```
|
||||
|
||||
>**NOTE**: Ensure that the samples has default values to test it out.
|
||||
### Verify
|
||||
|
||||
### To Uninstall
|
||||
**Delete the instances (CRs) from the cluster:**
|
||||
After all the setup is applied you can test that the kubernetes-operator is working by creating a game image and a server that uses it.
|
||||
Below are exxamples for an Image that runs a minecraft paper server on version 1.21.5 and a Server using that image.
|
||||
|
||||
```sh
|
||||
kubectl delete -k config/samples/
|
||||
#### Example Image
|
||||
|
||||
```yaml
|
||||
apiVersion: server-manager.acooldomain.co/v1alpha1
|
||||
kind: Image
|
||||
metadata:
|
||||
name: minecraft-paper-1-21-5
|
||||
spec:
|
||||
location: git.acooldomain.co/server-manager/minecraft:paper-1.21.5
|
||||
name: minecraft
|
||||
tag: paper-1.21.5
|
||||
working_dir: /opt/server
|
||||
ports:
|
||||
- port: 25565
|
||||
protocol: TCP
|
||||
|
||||
init_script:
|
||||
image: alpine:latest
|
||||
command:
|
||||
- /bin/sh
|
||||
args:
|
||||
- /bin/sh
|
||||
- "-c"
|
||||
- "echo eula=true >> /data/eula.txt"
|
||||
```
|
||||
|
||||
**Delete the APIs(CRDs) from the cluster:**
|
||||
#### Example Server
|
||||
|
||||
```sh
|
||||
make uninstall
|
||||
```yaml
|
||||
apiVersion: server-manager.acooldomain.co/v1alpha1
|
||||
kind: ServerManager
|
||||
metadata:
|
||||
name: test-server
|
||||
spec:
|
||||
storage: 10Gi
|
||||
browser:
|
||||
"on": true
|
||||
server:
|
||||
"on": true
|
||||
image: minecraft-paper-1-21-5
|
||||
ports:
|
||||
```
|
||||
|
||||
**UnDeploy the controller from the cluster:**
|
||||
#### Examples result
|
||||
|
||||
```sh
|
||||
make undeploy
|
||||
```
|
||||
After applying the following resources your environment should have several new resources created
|
||||
|
||||
## Project Distribution
|
||||
* PVCs
|
||||
* test-server
|
||||
* test-server-browser
|
||||
|
||||
Following are the steps to build the installer and distribute this project to users.
|
||||
* services
|
||||
* test-server
|
||||
* type: NodePort
|
||||
* ContainerPort: 25565
|
||||
* NodePort: Random Port
|
||||
|
||||
1. Build the installer for the image built and published in the registry:
|
||||
* Pods
|
||||
* test-server
|
||||
* test-server-browser
|
||||
|
||||
```sh
|
||||
make build-installer IMG=<some-registry>/kubernetes-operator:tag
|
||||
```
|
||||
|
||||
NOTE: The makefile target mentioned above generates an 'install.yaml'
|
||||
file in the dist directory. This file contains all the resources built
|
||||
with Kustomize, which are necessary to install this project without
|
||||
its dependencies.
|
||||
|
||||
2. Using the installer
|
||||
|
||||
Users can just run kubectl apply -f <URL for YAML BUNDLE> to install the project, i.e.:
|
||||
|
||||
```sh
|
||||
kubectl apply -f https://raw.githubusercontent.com/<org>/kubernetes-operator/<tag or branch>/dist/install.yaml
|
||||
```
|
||||
|
||||
## Contributing
|
||||
// TODO(user): Add detailed information on how you would like others to contribute to this project
|
||||
|
||||
**NOTE:** Run `make help` for more information on all potential `make` targets
|
||||
|
||||
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
|
||||
To delete the server and the related resources it is enough to delete the `server-manager.acooldomain.co` resource we created
|
||||
|
||||
## License
|
||||
|
||||
@ -111,4 +251,3 @@ distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
|
||||
23
config.yaml
23
config.yaml
@ -1,23 +0,0 @@
|
||||
domain_label: "ddns.acooldomain.co/hostname"
|
||||
default_domain: "acooldomain.co"
|
||||
browser:
|
||||
domain: games.acooldomain.co
|
||||
sub_path: /browsers
|
||||
auth_header: x-authentik-username
|
||||
cert_resolver: letsencrypt
|
||||
entrypoints:
|
||||
- websecure
|
||||
|
||||
additional_routes:
|
||||
- kind: Rule
|
||||
match: "Host(`games.acooldomain.co`) && PathPrefix(`/outpost.goauthentik.io/`)"
|
||||
priority: 15
|
||||
services:
|
||||
- kind: Service
|
||||
name: ak-outpost-traefik
|
||||
namespace: authentik
|
||||
port: 9000
|
||||
|
||||
middleware:
|
||||
name: authentik
|
||||
namespace: authentik
|
||||
@ -1,32 +1,22 @@
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
labels:
|
||||
control-plane: controller-manager
|
||||
app.kubernetes.io/name: kubernetes-operator
|
||||
app.kubernetes.io/managed-by: kustomize
|
||||
name: server-manager
|
||||
---
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: controller-manager
|
||||
namespace: server-manager
|
||||
name: servermanager-manager
|
||||
labels:
|
||||
control-plane: controller-manager
|
||||
control-plane: servermanager-manager
|
||||
app.kubernetes.io/name: kubernetes-operator
|
||||
app.kubernetes.io/managed-by: kustomize
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
control-plane: controller-manager
|
||||
control-plane: servermanager-manager
|
||||
replicas: 1
|
||||
template:
|
||||
metadata:
|
||||
annotations:
|
||||
kubectl.kubernetes.io/default-container: manager
|
||||
labels:
|
||||
control-plane: controller-manager
|
||||
control-plane: servermanager-manager
|
||||
spec:
|
||||
# TODO(user): Uncomment the following code to configure the nodeAffinity expression
|
||||
# according to the platforms which are supported by your solution.
|
||||
|
||||
@ -1,62 +0,0 @@
|
||||
---
|
||||
apiVersion: rbac.authorization.k8s.io/v1
|
||||
kind: ClusterRole
|
||||
metadata:
|
||||
name: manager-role
|
||||
rules:
|
||||
- resources:
|
||||
- persistentvolumeclaims
|
||||
- services
|
||||
verbs:
|
||||
- create
|
||||
- delete
|
||||
- get
|
||||
- list
|
||||
- patch
|
||||
- update
|
||||
- watch
|
||||
- resources:
|
||||
- pods
|
||||
verbs:
|
||||
- create
|
||||
- get
|
||||
- list
|
||||
- watch
|
||||
- apiGroups:
|
||||
- server-manager.acooldomain.co
|
||||
resources:
|
||||
- servermanagers
|
||||
verbs:
|
||||
- create
|
||||
- delete
|
||||
- get
|
||||
- list
|
||||
- patch
|
||||
- update
|
||||
- watch
|
||||
- apiGroups:
|
||||
- server-manager.acooldomain.co
|
||||
resources:
|
||||
- servermanagers/finalizers
|
||||
verbs:
|
||||
- update
|
||||
- apiGroups:
|
||||
- server-manager.acooldomain.co
|
||||
resources:
|
||||
- servermanagers/status
|
||||
verbs:
|
||||
- get
|
||||
- patch
|
||||
- update
|
||||
- apiGroups:
|
||||
- traefik.io
|
||||
resources:
|
||||
- ingressroutes
|
||||
verbs:
|
||||
- create
|
||||
- delete
|
||||
- get
|
||||
- list
|
||||
- patch
|
||||
- update
|
||||
- watch
|
||||
24
config/samples/minecraft_image-fabric-1.21.5.yaml
Normal file
24
config/samples/minecraft_image-fabric-1.21.5.yaml
Normal file
@ -0,0 +1,24 @@
|
||||
apiVersion: server-manager.acooldomain.co/v1alpha1
|
||||
kind: Image
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/name: kubernetes-operator
|
||||
app.kubernetes.io/managed-by: kustomize
|
||||
name: minecraft-fabric-1-21-5
|
||||
spec:
|
||||
location: git.acooldomain.co/server-manager/minecraft:fabric-1.21.5
|
||||
name: minecraft
|
||||
tag: fabric-1.21.5
|
||||
working_dir: /opt/server
|
||||
ports:
|
||||
- port: 25565
|
||||
protocol: TCP
|
||||
|
||||
init_script:
|
||||
image: alpine:latest
|
||||
command:
|
||||
- /bin/sh
|
||||
args:
|
||||
- /bin/sh
|
||||
- "-c"
|
||||
- "echo eula=true >> /data/eula.txt"
|
||||
24
config/samples/minecraft_image-paper-1.21.5.yaml
Normal file
24
config/samples/minecraft_image-paper-1.21.5.yaml
Normal file
@ -0,0 +1,24 @@
|
||||
apiVersion: server-manager.acooldomain.co/v1alpha1
|
||||
kind: Image
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/name: kubernetes-operator
|
||||
app.kubernetes.io/managed-by: kustomize
|
||||
name: minecraft-paper-1-21-5
|
||||
spec:
|
||||
location: git.acooldomain.co/server-manager/minecraft:paper-1.21.5
|
||||
name: minecraft
|
||||
tag: paper-1.21.5
|
||||
working_dir: /opt/server
|
||||
ports:
|
||||
- port: 25565
|
||||
protocol: TCP
|
||||
|
||||
init_script:
|
||||
image: alpine:latest
|
||||
command:
|
||||
- /bin/sh
|
||||
args:
|
||||
- /bin/sh
|
||||
- "-c"
|
||||
- "echo eula=true >> /data/eula.txt"
|
||||
@ -7,7 +7,7 @@ metadata:
|
||||
name: minecraft-paper-1-21-4
|
||||
spec:
|
||||
location: git.acooldomain.co/server-manager/minecraft:paper-1.21.4
|
||||
name: minecraft:paper-1.21.4
|
||||
name: minecraft
|
||||
tag: paper-1.21.4
|
||||
working_dir: /opt/server
|
||||
ports:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user