Skip to content
Merged
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
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Resource Glue Operator
# Kubernetes Glue Operator

Resource Glue Operator is a powerful Kubernetes **meta operator** that allows you to create other **operators in a declarative** way by **simply
Kubernetes Glue Operator is a powerful Kubernetes **meta operator** that allows you to create other **operators in a declarative** way by **simply
applying a custom resource**.

It provides facilities to compose Kubernetes resources and describes how the resource
Expand All @@ -26,11 +26,11 @@ Either in the discussion section here on GitHub or at [Kubernetes Slack Operator
The project introduces two Kubernetes custom resources `Glue` and `GlueOperator`.
You can use `GlueOperator` to define your own operator.
Let's take a look at an example, where we define an operator for WebPage custom resource, that represents a static website served from the Cluster. (You can see the
[full example here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/sample/webpage))
[full example here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/sample/webpage))

```yaml

apiVersion: "resourceglueoperator.sample/v1"
apiVersion: "glueoperator.sample/v1"
kind: WebPage
metadata:
name: hellows
Expand All @@ -47,19 +47,19 @@ spec:
</html>
```

To create an operator (or more precisely the controller part) with `resource-glue-operator` we have first apply
the [CRD for WebPage](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/sample/webpage/webpage.crd.yml).
To create an operator (or more precisely the controller part) with `kubernetes-glue-operator` we have first apply
the [CRD for WebPage](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/sample/webpage/webpage.crd.yml).
To define how the `WebPage` should be reconciled, thus what resources should be created for
a `WebPage`, we prepare a `GlueOperator`:

```yaml
apiVersion: io.csviri.operator.resourceglue/v1beta1
apiVersion: io.csviri.operator.glue/v1beta1
kind: GlueOperator
metadata:
name: webpage-operator
spec:
parent:
apiVersion: resourceglueoperator.sample/v1 # watches all the custom resource of type WebPage
apiVersion: glueoperator.sample/v1 # watches all the custom resource of type WebPage
kind: WebPage
resources:
- name: htmlconfigmap
Expand Down Expand Up @@ -127,11 +127,11 @@ resources are applied, however, there are certain cases when this is needed also
The following example shows how to deploy a [dynamic admission controller](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/) that mutates
all the `Pods`, adding annotation on them. Note that this is a tricky situation since the endpoint for the `MutatingWebhookConfiguration` is also a `Pod`, thus 'Pods' should be
first up and running before the configuration is applied, otherwise, the mutation webhook will block the changes on the pods, which would render the cluster unable to manage `Pods'.
(Irrelevant details are omitted, see the full version [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/sample/mutation/mutation.glue.yaml),
see the full E2E test [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/java/io/csviri/operator/resourceglue/sample/mutation/MutationWebhookDeploymentE2E.java))
(Irrelevant details are omitted, see the full version [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/sample/mutation/mutation.glue.yaml),
see the full E2E test [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/java/io/csviri/operator/glue/sample/mutation/MutationWebhookDeploymentE2E.java))

```yaml
apiVersion: io.csviri.operator.resourceglue/v1beta1
apiVersion: io.csviri.operator.glue/v1beta1
kind: Glue
metadata:
name: mutation-webhook-deployment
Expand Down Expand Up @@ -202,5 +202,5 @@ spec:
- pods
```

The `dependsOn` relation is a useful concept in certain situations, that might be familiar from other infrustructure-as-a-code tools, `resource-glue-operator` adopts it to Kubernetes operators.
The `dependsOn` relation is a useful concept in certain situations, that might be familiar from other infrustructure-as-a-code tools, `kubernetes-glue-operator` adopts it to Kubernetes operators.

10 changes: 5 additions & 5 deletions docs/comparison.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Rational and Comparison to Similar Solutions

There are other solutions comparable to *resource-glue-operator* that work (or limited to work) on top
There are other solutions comparable to *kubernetes-glue-operator* that work (or limited to work) on top
of Kubernetes resources in a language-independent way and try to simplify the operator
development but make some compromises. *resource-glue-operator* has some nice properties:
development but make some compromises. *kubernetes-glue-operator* has some nice properties:

1. **input is only a custom resource** (`Glue` or `GlueOperator`) that makes it very easy to set up, maintain,
and start with. You don't have to build the project, all you have to manage is `yaml` files (CRD, inputs, deployment)
Expand All @@ -25,7 +25,7 @@ this is probably the most elegant way to go.
As mentioned before there are solutions that are comparable to ours, and all of them have advantages and disadvantages:

- [**metacontroller**](https://github.com/metacontroller/metacontroller) - it a very interesting solution that allows
to implement controller is any language programming language, just like in the case of *resource-glue-operator* takes a custom resource as an input, which
to implement controller is any language programming language, just like in the case of *kubernetes-glue-operator* takes a custom resource as an input, which
describes the Kubernetes resources that we are interested in - or watched/managed for a custom resource.
However, it does not describe the desired state that is up to you to implement in the form of a web service endpoint,
where all the inputs are received and the output is a list of desired resources.
Expand All @@ -37,13 +37,13 @@ As mentioned before there are solutions that are comparable to ours, and all of

In summary *metacontroller* is a bit more generic solution this moment,
but with additional complexity to manage, and much harder to start with.
The main practical difference is in supporting ["bulk resources"](https://github.com/csviri/resource-glue-operator/issues/75)
The main practical difference is in supporting ["bulk resources"](https://github.com/csviri/kubernetes-glue-operator/issues/75)
we will also support it in future versions.

- [Helm Operators](https://sdk.operatorframework.io/docs/building-operators/helm/tutorial/) - are a very efficient
way to convert a helm chart into a controller. It also makes it very easy to start and use.
However, the controller still needs to be build (the helm chart is not just an input configuration),
does not handle related resources, and does not support ordering. In this terms is a bit more limited
than *resource-glue-operator*.
than *kubernetes-glue-operator*.

- [Crossplane Composition](https://docs.crossplane.io/latest/concepts/compositions/) TODO
14 changes: 7 additions & 7 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,35 +9,35 @@ Start a local Kubernetes cluster using for example [Minikube](https://minikube.s
Apply the CustomResourceDefinitions:

```bash
kubectl apply -f https://github.com/csviri/resource-glue-operator/releases/latest/download/glues.io.csviri.operator.resourceglue-v1.yml -f https://github.com/csviri/resource-glue-operator/releases/latest/download/glueoperators.io.csviri.operator.resourceglue-v1.yml
kubectl apply -f https://github.com/csviri/kubernetes-glue-operator/releases/latest/download/glues.io.csviri.operator.glue-v1.yml -f https://github.com/csviri/kubernetes-glue-operator/releases/latest/download/glueoperators.io.csviri.operator.glue-v1.yml
```

Deploy the `resource-glue-operator`:
Deploy the `kubernetes-glue-operator`:

```bash
kubectl apply -f https://github.com/csviri/resource-glue-operator/releases/latest/download/kubernetes.yml
kubectl apply -f https://github.com/csviri/kubernetes-glue-operator/releases/latest/download/kubernetes.yml
```

Note that this deployment gives the controller access to all the resources on the cluster, this is not what you might want in production.

## Try out the [WebPage Sample](https://github.com/csviri/resource-workflow-operator/tree/main/src/test/resources/sample/webpage)
## Try out the [WebPage Sample](https://github.com/csviri/kubernetes-glue-operator/tree/main/src/test/resources/sample/webpage)

First apply the CustomResourceDefinition for `WebPage` :

```bash
kubectl apply -f https://raw.githubusercontent.com/csviri/resource-glue-operator/main/src/test/resources/sample/webpage/webpage.crd.yaml
kubectl apply -f https://raw.githubusercontent.com/csviri/kubernetes-glue-operator/main/src/test/resources/sample/webpage/webpage.crd.yaml
```

Apply the `GlueOperator` for `WebPage`:

```bash
kubectl apply -f https://raw.githubusercontent.com/csviri/resource-glue-operator/main/src/test/resources/sample/webpage/webpage.operator.yaml
kubectl apply -f https://raw.githubusercontent.com/csviri/kubernetes-glue-operator/main/src/test/resources/sample/webpage/webpage.operator.yaml
```

Create a new static `WebPage`:

```bash
kubectl apply -f https://raw.githubusercontent.com/csviri/resource-glue-operator/main/src/test/resources/sample/webpage/webpage.sample.yaml
kubectl apply -f https://raw.githubusercontent.com/csviri/kubernetes-glue-operator/main/src/test/resources/sample/webpage/webpage.sample.yaml
```

All done! Check the resources created, if using minikube you can open the served WebPage with `minikube service webpage1`.
Expand Down
38 changes: 19 additions & 19 deletions docs/reference.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ of [Java Operator SDK](https://github.com/operator-framework/java-operator-sdk)
Although it is limited only to Kubernetes resources it makes it very easy to use in language-independent
(DependentResources in JOSDK are also covering external resources) way.

## [Glue resource](https://github.com/csviri/resource-glue-operator/releases/latest/download/glues.io.csviri.operator.resourceglue-v1.yml)
## [Glue resource](https://github.com/csviri/kubernetes-glue-operator/releases/latest/download/glues.glue-v1.yml)

`Glue` is the heart of the operator. Note that `GlueOperator` controller just creates a new `Glue` with a related resource,
for each parent custom resource. `Glue` defines `resources` (sometimes referred to as managed resources) and `related resources`:
Expand Down Expand Up @@ -37,16 +37,16 @@ The `resources` section is a list of resources to be reconciled. It has several

At the moment there are two types of built-in conditions provided:

- **`ReadyCondition`** - check if a resource is up and running. Use it only as a `readyPostCondition`. See sample usage [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/sample/mutation/mutation.glue.yaml#L24-L25).
- **`ReadyCondition`** - check if a resource is up and running. Use it only as a `readyPostCondition`. See sample usage [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/sample/mutation/mutation.glue.yaml#L24-L25).
- **`JSCondition`** - a generic condition, that allows writing conditions in JavaScript. As input, all the resources are available which
are either managed or related. The script should return a boolean value.
See accessing the related resource in [WebPage sample](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/sample/webpage/webpage.operator.yaml#L62-L64),
and cross-referencing resources [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/resourceglue/TwoResourcesAndCondition.yaml#L23-L28).
See accessing the related resource in [WebPage sample](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/sample/webpage/webpage.operator.yaml#L62-L64),
and cross-referencing resources [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/glue/TwoResourcesAndCondition.yaml#L23-L28).

### Related resources

Related resources are resources that are not managed (not created, updated, or deleted) during reconciliation, but serve as an input for it.
See sample usage within `Glue` [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/resourceglue/RelatedResourceSimpleWithCondition.yaml)
See sample usage within `Glue` [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/glue/RelatedResourceSimpleWithCondition.yaml)
The following attributes can be defined for a related resource:

- **`name`** - same as for managed resource, unique identifier, used to reference the resource.
Expand All @@ -59,15 +59,15 @@ The following attributes can be defined for a related resource:
Both in `JSCondition` and resource templates other resources can be referenced by the name.

If there are more `resourceNames` specified for a related resource, the resource is referenced in a form
`[related resource name]#[resource name]`. See sample [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/resourceglue/MultiNameRelatedResource.yaml).
`[related resource name]#[resource name]`. See sample [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/glue/MultiNameRelatedResource.yaml).

When a resource `B` references another resource `A`, resource `A` will be guaranteed to be in the cache - especially for initial reconciliation when the resource is created -
only if `B` depends on `A` on it. This is natural, in other words, after reconciliation up-to-date version of the resource is guaranteed to be in the cache after reconciliation.
See sample resource cross-referencing [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/resourceglue/CrossReferenceResource.yaml).
See sample resource cross-referencing [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/glue/CrossReferenceResource.yaml).

The metadata of `Glue` can be referenced under `glueMetadata`, see sample [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/resourceglue/TemplateForConcurrency.yaml#L12-L12)
The metadata of `Glue` can be referenced under `glueMetadata`, see sample [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/glue/TemplateForConcurrency.yaml#L12-L12)

In addition to that in `GlueOperator` the **`parent`** attribute can be used to reference the parent resource on which behalf the resources are created. See sample [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/resourceglueoperator/Templating.yaml).
In addition to that in `GlueOperator` the **`parent`** attribute can be used to reference the parent resource on which behalf the resources are created. See sample [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/glueoperator/Templating.yaml).

### Reconciliation notes

Expand All @@ -78,22 +78,22 @@ for a resource that depends on it.

The `DependentResource` implementation of JOSDK makes all kinds of optimizations on the reconciliation which are utilized (or will be also here).

## [GlueOperator resource](https://github.com/csviri/resource-glue-operator/releases/latest/download/glueoperators.io.csviri.operator.resourceglue-v1.yml)
## [GlueOperator resource](https://github.com/csviri/kubernetes-glue-operator/releases/latest/download/glueoperators.glue-v1.yml)

The specs of `GlueOperator` are almost identical to `Glue`, it just adds one additional attribute **`parent`**,
which has two sub-attributes: **`apiVersion`** and **`kind`**. This structure specifies the resource
types - usually but not necessarily custom resources - watched.

See minimal `GlueOperator` [here](https://github.com/csviri/resource-workflow-operator/blob/main/src/test/resources/resourceglueoperator/Templating.yaml).
See minimal `GlueOperator` [here](https://github.com/csviri/kubernetes-glue-operator/blob/main/src/test/resources/glueoperator/Templating.yaml).

## Deploying `resource-glue-operator`
## Deploying `kubernetes-glue-operator`

Implementation is using [Quarkus Operator SDK (QOSDK)](https://github.com/quarkiverse/quarkus-operator-sdk),
the default [configuration options](https://docs.quarkiverse.io/quarkus-operator-sdk/dev/includes/quarkus-operator-sdk.html)
defined by QOSDK can be overridden using environment variables.

With every release, there are Kubernetes resources provided to make an initial deployment very simple.
See `kubernetes.yml` in [release assets](https://github.com/csviri/resource-glue-operator/releases).
See `kubernetes.yml` in [release assets](https://github.com/csviri/kubernetes-glue-operator/releases).
While we will provide more options, users are encouraged to enhance/adjust this for their purposes.

Since the project is a meta-controller, it needs to have access rights to all the resources it manages.
Expand All @@ -103,8 +103,8 @@ and `["list", "watch"]` for related resources.

The project is mainly tested with cluster-scoped deployment, however, QOSDK namespace-scoped deployments are also supported.

See also the upcoming deployment modes/options: [sharding with label selectors](https://github.com/csviri/resource-glue-operator/issues/50),
[watching only one custom resources type](https://github.com/csviri/resource-glue-operator/issues/54)
See also the upcoming deployment modes/options: [sharding with label selectors](https://github.com/csviri/kubernetes-glue-operator/issues/50),
[watching only one custom resources type](https://github.com/csviri/kubernetes-glue-operator/issues/54)

## Implementation details and performance

Expand All @@ -127,12 +127,12 @@ Note that none of the limitations are unsolvable, and will be continuously remov

## Samples

1. [WebPage](https://github.com/csviri/resource-glue-operator/tree/main/src/test/resources/sample/webpage) `GlueOperator`, serves a static website from the cluster.
1. [WebPage](https://github.com/csviri/kubernetes-glue-operator/tree/main/src/test/resources/sample/webpage) `GlueOperator`, serves a static website from the cluster.
To achieve this, it creates three resources a `Deployment` running Nginx, a `ConfigMap` that contains the HTML file an mounted to nginx, a `Service` and an optional `Ingress`
to expose the static web page.
3. [Muatation Hook Deployment](https://github.com/csviri/resource-workflow-operator/tree/main/src/test/resources/sample/mutation), described on the project home page.
4. [Additional `Glue` samples](https://github.com/csviri/resource-workflow-operator/tree/main/src/test/resources/resourceglue), note that these are used for integration testing.
5. [Additional `GlueOperator` samples](https://github.com/csviri/resource-workflow-operator/tree/main/src/test/resources/resourceglueoperator), also used for integration testing.
3. [Muatation Hook Deployment](https://github.com/csviri/kubernetes-glue-operator/tree/main/src/test/resources/sample/mutation), described on the project home page.
4. [Additional `Glue` samples](https://github.com/csviri/kubernetes-glue-operator/tree/main/src/test/resources/glue), note that these are used for integration testing.
5. [Additional `GlueOperator` samples](https://github.com/csviri/kubernetes-glue-operator/tree/main/src/test/resources/glueoperator), also used for integration testing.

## Related documents

Expand Down
4 changes: 2 additions & 2 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>io.csviri.operator.resourceglue</groupId>
<artifactId>resource-glue-operator</artifactId>
<groupId>io.csviri.operator.glue</groupId>
<artifactId>kubernetes-glue-operator</artifactId>
<version>0.1.1-SNAPSHOT</version>
<packaging>jar</packaging>
<name>Resource Flow Operator</name>
Expand Down
Loading