Skip to content

Commit c728263

Browse files
phlgphlg
committed
Update README
1 parent 5b555df commit c728263

File tree

1 file changed

+145
-10
lines changed

1 file changed

+145
-10
lines changed

‎README.md‎

Lines changed: 145 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,12 @@ This Operator SDK based tool aims at managing S3 related resources (buckets, pol
44

55
## At a glance
66

7-
- Current S3 providers : [Minio](https://github.com/InseeFrLab/s3-operator/blob/main/controllers/s3/factory/minioS3Client.go) (a [mock](https://github.com/InseeFrLab/s3-operator/blob/main/controllers/s3/factory/mockedS3Client.go) implementation is also present for testing purposes)
7+
- Current S3 providers : [Minio](https://github.com/InseeFrLab/s3-operator/blob/main/controllers/s3/factory/minioS3Client.go)
88
- Currently managed S3 resources : [buckets](https://github.com/InseeFrLab/s3-operator/blob/main/api/v1alpha1/bucket_types.go), [policies](https://github.com/InseeFrLab/s3-operator/blob/main/api/v1alpha1/policy_types.go)
99

1010
## Compatibility
1111

12-
So far, this operator has been tested with :
12+
This operator has been successfully tested with :
1313

1414
- Kubernetes : 1.25, 1.26
1515
- MinIO : 2023-05-27T05:56:19Z
@@ -23,22 +23,156 @@ At its heart, the operator revolves around CRDs that match S3 resources :
2323

2424
The custom resources based on these CRDs are a somewhat simplified projection of the real S3 resources. From the operator's point of view :
2525

26-
- A `Bucket` CR only has a name, a quota (actually two, more on this below), and optionally, a set of paths
27-
- A `Policy` CR has a name, and its actual content (IAM JSON)
26+
- A `Bucket` CR matches a S3 bucket, and only has a name, a quota (actually two, [see Bucket example in *Usage* section below](#bucket)), and optionally, a set of paths
27+
- A `Policy` CR matches a "canned" policy (not a bucket policy, but a global one, that can be attached to a user), and has a name, and its actual content (IAM JSON)
2828

2929
Each custom resource based on these CRDs on Kubernetes is to be matched with a resource on the S3 instance. If the CR and the corresponding S3 resource diverge, the operator will create or update the S3 resource to bring it back to .
3030

3131
Two important caveats :
3232

33-
- It is one-way - if something happens on the S3 side directly (instead of going through the CRs), the operator has no way of reacting. At best, the next trigger will overwrite the S3 state with the declared state in the k8s custom resource.
34-
- For now, the operator won't delete any resource on S3 - if a CR is removed, its matching resource on S3 will still be present. This behavior was primarily picked to avoid data loss for bucket, but also applied to policies - which could be debatable.
33+
- It is one-way - if something happens on the S3 side directly (instead of going through the CRs), the operator ha s no way of reacting. At best, the next trigger will overwrite the S3 state with the declared state in the k8s custom resource.
34+
- For now, the operator won't delete any resource on S3 - if a CR is removed, its matching resource on S3 will still be present. This behavior was primarily picked to avoid data loss for bucket, but also applied to policies.
3535

36-
---
36+
## Installation
37+
38+
The S3 operator is provided either in source form through this repositoy, or already built as a Docker image available on [Docker Hub](https://hub.docker.com/r/inseefrlab/s3-operator).
39+
40+
### Helm
41+
42+
With this Docker image, the recommended way of installing S3 Operator on your cluster is to use the Helm chart provided in the dedicated repository : https://github.com/InseeFrLab/helm-charts/tree/master/charts/s3-operator. Among other things, the chart takes care of managing a (Kubernetes) ServiceAccount for the operator to run as. The most basic way of using this chart would be :
43+
44+
```shell
45+
helm repo add inseefrlab https://inseefrlab.github.io/helm-charts # or [helm repo update] if already available
46+
helm install <name> s3-operator --values <yaml-file/url> # see below for the parameters
3747
```
38-
NB : the remainder of this README comes from the auto-generated Operator SDK placeholder. As it remains a useful reference, it is left as is until it's replaced by a documentation more accurately focused on this operator.
48+
49+
### Running from source
50+
51+
Alternatively, if you just wish to try out the operator without actually, it is also possible to just clone this repository, and run the operator locally - outside of the Kubernetes cluster. This requires Go 1.19+ :
52+
53+
```shell
54+
git clone https://github.com/InseeFrLab/s3-operator.git # or use a tag/release
55+
cd s3-operator
56+
go run main.go --s3-endpoint-url *** --s3-access-key *** --s3-secret-key *** # see below for the parameters
3957
```
40-
---
4158

59+
To quote the Operator SDK README (also visible below), running the operator this way *will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).* RBAC-wise, you need to be able to freely manipulate the custom resources associated to the operator (`Bucket` and `Policy`) in every namespace - [see also the generated ClusterRole manifest](https://github.com/InseeFrLab/s3-operator/blob/main/config/rbac/role.yaml).
60+
61+
### Kustomize
62+
63+
Finally, as this operator was generated through Operator SDK, it should be possible to use kustomize to bootstrap the operator as well. Though this method is untested by the maintainers of the project, the Operator SDK generated guidelines ([see below](#operator-sdk-generated-guidelines)) might help in making use of the various kustomize configuration files, possibly through the use of `make`.
64+
65+
## Configuration
66+
67+
The operator exposes a few parameters, meant to be set as arguments, though it's possible to use environment variables for some of them. When an environment variable is available, it takes precedence over the flag.
68+
69+
The parameters are summarized in the table below :
70+
71+
| Flag name | Default | Environment variable | Multiple values allowed | Description |
72+
|---------------------------------|------------------|----------------------|-------------------------|-------------|
73+
| `health-probe-bind-address` | `:8081` | - | no | The address the probe endpoint binds to. Comes from Operator SDK.
74+
| `leader-elect` | `false` | - | no | Enable leader election for controller manager. Enabling this will ensure there is only one active controller manager. Comes from Operator SDK.
75+
| `metrics-bind-address` | `:8080` | - | no | The address the metric endpoint binds to. Comes from Operator SDK.
76+
| `region` | `us-east-1` | - | no | The region to configure for the S3 client.
77+
| `s3-access-key` | - | `S3_ACCESS_KEY` | no | The access key used to interact with the S3 server.
78+
| `s3-ca-certificate-base64` | - | - | yes | (Optional) Base64 encoded, PEM format CA certificate, for https requests to the S3 server.
79+
| `s3-ca-certificate-bundle-path` | - | - | no | (Optional) Path to a CA certificates bundle file, for https requests to the S3 server.
80+
| `s3-endpoint-url` | `localhost:9000` | - | no | Hostname (or hostname:port) of the S3 server.
81+
| `s3-provider` | `minio` | - | no | S3 provider (possible values : `minio`, `mockedS3Provider`)
82+
| `s3-secret-key` | - | `S3_SECRET_KEY` | no | The secret key used to interact with the S3 server.
83+
| `useSsl` | `true` | - | no | Use of SSL/TLS to connect to the S3 server
84+
85+
86+
## Usage
87+
88+
- The first step is to install the CRDs in your Kubernetes cluster. The Helm chart will do just that, but it is also possible to do it manually - the manifests are in the [`config/crd/bases`](https://github.com/InseeFrLab/s3-operator/tree/main/config/crd/bases) folder.
89+
- With the CRDs available and the operator running, all that's left is to create some custom resources - you'll find some commented examples in the subsections below.
90+
- As soon as a custom resource is created, the operator will react, and create or update a S3 resource accordingly.
91+
- The same will happen if you modify a CR - the operator will adjust the S3 bucket or policy accordingly - with the notable exception that it will not delete paths for buckets.
92+
- Upon deleting a CR, the corresponding bucket or policy will be left as is, as mentioned in the [*Description* section above](#description)
93+
94+
### Bucket example
95+
96+
```yaml
97+
apiVersion: s3.onyxia.sh/v1alpha1
98+
kind: Bucket
99+
metadata:
100+
labels:
101+
app.kubernetes.io/name: bucket
102+
app.kubernetes.io/instance: bucket-sample
103+
app.kubernetes.io/part-of: s3-operator
104+
app.kubernetes.io/managed-by: kustomize
105+
app.kubernetes.io/created-by: s3-operator
106+
name: bucket-sample
107+
spec:
108+
# Bucket name (on S3 server, as opposed to the name of the CR)
109+
name: dummy-bucket
110+
111+
# Paths to create on the bucket
112+
# As it is not possible to create empty paths on a S3 server, (limitation of either S3,
113+
# or at least Minio, the only currently implemented provider), this will actually create
114+
# a .keep file at the deepest folder in the path.
115+
paths:
116+
- a_path
117+
- another/deeper/path
118+
119+
# Quota to set on the bucket, in bytes (so 1000000000 would be 1GB).
120+
# This is split over two different parameters, although there is only one actual quota
121+
# - "default" is required, and is used as the baseline
122+
# - "override" is optional, and as the name implies, takes precedence over "default"
123+
# Though clumsy, this pattern (for lack of a better word) allows to easily track the growth
124+
# of any given bucket. If this is not useful to you, you can safely skip using "override".
125+
quota:
126+
default: 10000000
127+
# override: 20000000
128+
129+
```
130+
131+
### Policy example
132+
133+
```yaml
134+
apiVersion: s3.onyxia.sh/v1alpha1
135+
kind: Policy
136+
metadata:
137+
labels:
138+
app.kubernetes.io/name: policy
139+
app.kubernetes.io/instance: policy-sample
140+
app.kubernetes.io/part-of: s3-operator
141+
app.kubernetes.io/managed-by: kustomize
142+
app.kubernetes.io/created-by: s3-operator
143+
name: policy-sample
144+
spec:
145+
# Policy name (on S3 server, as opposed to the name of the CR)
146+
name: dummy-policy
147+
148+
# Content of the policy, as a multiline string
149+
# This should be IAM compliant JSON - follow the guidelines of the actual
150+
# S3 provider you're using, as sometimes only a subset is available.
151+
policyContent: >-
152+
{
153+
"Version": "2012-10-17",
154+
"Statement": [
155+
{
156+
"Effect": "Allow",
157+
"Action": [
158+
"s3:*"
159+
],
160+
"Resource": [
161+
"arn:aws:s3:::dummy-bucket",
162+
"arn:aws:s3:::dummy-bucket/*"
163+
]
164+
}
165+
]
166+
}
167+
168+
169+
```
170+
171+
## Operator SDK generated guidelines
172+
173+
<details>
174+
175+
<summary><strong>Click to fold / unfold</strong></summary>
42176
43177
## Getting Started
44178
@@ -79,7 +213,6 @@ make undeploy
79213
```
80214

81215
## Contributing
82-
// TODO(user): Add detailed information on how you would like others to contribute to this project
83216

84217
### How it works
85218
This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
@@ -112,3 +245,5 @@ make manifests
112245
**NOTE:** Run `make --help` for more information on all potential `make` targets
113246

114247
More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
248+
249+
</details>

0 commit comments

Comments
 (0)