From 3a85e44ad4c1128fc78aba2afaba0c940225cecd Mon Sep 17 00:00:00 2001 From: ACoolName Date: Mon, 19 May 2025 15:35:27 +0300 Subject: [PATCH] updated readme --- README.md | 267 +++++++++++++----- config.yaml | 23 -- config/manager/manager.yaml | 18 +- config/role/role.yaml | 62 ---- .../minecraft_image-fabric-1.21.5.yaml | 24 ++ .../samples/minecraft_image-paper-1.21.5.yaml | 24 ++ .../server-manager_v1alpha1_image.yaml | 2 +- 7 files changed, 256 insertions(+), 164 deletions(-) delete mode 100644 config.yaml delete mode 100644 config/role/role.yaml create mode 100644 config/samples/minecraft_image-fabric-1.21.5.yaml create mode 100644 config/samples/minecraft_image-paper-1.21.5.yaml diff --git a/README.md b/README.md index 9dfab3b..7c0702d 100644 --- a/README.md +++ b/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=/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 `` with the desired namespace): + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: server-manager-config + 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 `` is the namespace the operator would be deployed to ```sh -make deploy IMG=/kubernetes-operator:tag +kubectl apply -n -f https://git.acooldomain.co/server-manager/kubernetes-operator/raw/branch/main/config/rbac/service-account.yaml +kubectl apply -n -f https://git.acooldomain.co/server-manager/kubernetes-operator/raw/branch/main/config/rbac/role.yaml +kubectl apply -n -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 -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=/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 to install the project, i.e.: - -```sh -kubectl apply -f https://raw.githubusercontent.com//kubernetes-operator//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. - diff --git a/config.yaml b/config.yaml deleted file mode 100644 index c4d75cc..0000000 --- a/config.yaml +++ /dev/null @@ -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 diff --git a/config/manager/manager.yaml b/config/manager/manager.yaml index 7b2df1b..a8feb8b 100644 --- a/config/manager/manager.yaml +++ b/config/manager/manager.yaml @@ -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. diff --git a/config/role/role.yaml b/config/role/role.yaml deleted file mode 100644 index 7f58d75..0000000 --- a/config/role/role.yaml +++ /dev/null @@ -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 diff --git a/config/samples/minecraft_image-fabric-1.21.5.yaml b/config/samples/minecraft_image-fabric-1.21.5.yaml new file mode 100644 index 0000000..f07d8a7 --- /dev/null +++ b/config/samples/minecraft_image-fabric-1.21.5.yaml @@ -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" diff --git a/config/samples/minecraft_image-paper-1.21.5.yaml b/config/samples/minecraft_image-paper-1.21.5.yaml new file mode 100644 index 0000000..a66ae28 --- /dev/null +++ b/config/samples/minecraft_image-paper-1.21.5.yaml @@ -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" diff --git a/config/samples/server-manager_v1alpha1_image.yaml b/config/samples/server-manager_v1alpha1_image.yaml index d7740d2..bbea395 100644 --- a/config/samples/server-manager_v1alpha1_image.yaml +++ b/config/samples/server-manager_v1alpha1_image.yaml @@ -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: