From 9a0b1987a544c3116231467d9a5cb9b3f02ea602 Mon Sep 17 00:00:00 2001 From: Sina Date: Sat, 6 Jan 2024 15:08:37 +0330 Subject: [PATCH 1/3] updated readme --- README.md | 149 ++++++++++++++++++++++-------------------------------- 1 file changed, 61 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 29c3f7b..5cc2d37 100644 --- a/README.md +++ b/README.md @@ -1,93 +1,66 @@ -# simpleauthenticator -// TODO(user): Add simple overview of use/purpose - -## Description -Kind of an authentication offloader -## Getting Started -You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster. -**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows). - -### Running on the cluster -1. Install Instances of Custom Resources: - -```sh -kubectl apply -f config/samples/ -``` - -2. Build and push your image to the location specified by `IMG`: - -```sh -make docker-build docker-push IMG=/basicauthenticator:tag -``` - -3. Deploy the controller to the cluster with the image specified by `IMG`: - -```sh -make deploy IMG=/basicauthenticator:tag -``` - -### Uninstall CRDs -To delete the CRDs from the cluster: - -```sh -make uninstall -``` - -### Undeploy controller -UnDeploy the controller from the cluster: - -```sh -make undeploy +# Simple Authenticator + +## Introduction + +The Simple Authenticator is a Kubernetes-based tool designed to streamline and enhance basic authentication within a cluster. It serves as a crucial component for managing microservices' security and performance efficiently. + +### Purpose + +In Kubernetes environments, effective authentication is essential, especially when dealing with internal traffic between microservices. The Simple Authenticator simplifies this process, providing a straightforward solution for handling West-East Traffic within the cluster. + +### Features + +- **NGINX Deployment:** Supports both sidecar and standalone deployment of NGINX for secure authentication. +- **Adaptive Scale Support:** Dynamically scales based on the number of pods in the targeted service, optimizing resource utilization. +- **Plain Username and Password Authentication:** Simplifies credential management by transforming secrets to NGINX preferences automatically. + +The Simple Authenticator ensures that authentication between microservices is both secure and efficient, contributing to a robust and well-architected Kubernetes environment. + +### Installation +# Installation of Simple Authenticator + +## Using Makefile +Deploy Simple Authenticator using the Makefile: + + ```sh + make deploy + ``` + +## Using Helm +Deploy Simple Authenticator using Helm: + + ```sh + helm upgrade --install simple-authenticator oci://ghcr.io/snapp-incubator/simple-authenticator/helm-charts/simple-authenticator --version v0.1.8 + ``` + +## Using OLM (Operator Lifecycle Manager) +All the operator releases are bundled and pushed to the [Snappcloud hub](https://github.com/snapp-incubator/snappcloud-hub) which is a hub for the catalog sources. Install using Operator Lifecycle Manager (OLM) by following these steps: +1. Install [snappcloud hub catalog-source](https://github.com/snapp-incubator/snappcloud-hub/blob/main/catalog-source.yml) +2. Apply the subscription manifest as shown below: +```yaml + apiVersion: operators.coreos.com/v1alpha1 + kind: Subscription + metadata: + name: simple-authenticator + namespace: operators + spec: + channel: stable-v1 + installPlanApproval: Automatic + name: simple-authenticator + source: snappcloud-hub-catalog + sourceNamespace: openshift-marketplace + config: + resources: + limits: + cpu: 2 + memory: 2Gi + requests: + cpu: 1 + memory: 1Gi ``` ## Contributing -// TODO(user): Add detailed information on how you would like others to contribute to this project - -### How it works -This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/). - -It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/), -which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster. - -### Test It Out -1. Install the CRDs into the cluster: - -```sh -make install -``` - -2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): - -```sh -make run -``` - -**NOTE:** You can also run this in one step by running: `make install run` - -### Modifying the API definitions -If you are editing the API definitions, generate the manifests such as CRs or CRDs using: - -```sh -make manifests -``` - -**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) +Contributions are warmly welcomed. Feel free to submit issues or pull requests. ## License - -Copyright 2023. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -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. - +This project is licensed under the [Apache License 2.0](https://github.com/snapp-incubator/s3-operator/blob/main/LICENSE). \ No newline at end of file From a01b9695ed6e6a0756064512e7cff299bea7bae9 Mon Sep 17 00:00:00 2001 From: Sina Date: Sat, 6 Jan 2024 15:54:14 +0330 Subject: [PATCH 2/3] updated doc --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 5cc2d37..cbed1da 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,7 @@ The Simple Authenticator is a Kubernetes-based tool designed to streamline and e ### Purpose -In Kubernetes environments, effective authentication is essential, especially when dealing with internal traffic between microservices. The Simple Authenticator simplifies this process, providing a straightforward solution for handling West-East Traffic within the cluster. - +In Kubernetes environments, effective authentication is essential, especially when dealing with internal traffic between microservices. ### Features - **NGINX Deployment:** Supports both sidecar and standalone deployment of NGINX for secure authentication. @@ -16,7 +15,6 @@ In Kubernetes environments, effective authentication is essential, especially wh The Simple Authenticator ensures that authentication between microservices is both secure and efficient, contributing to a robust and well-architected Kubernetes environment. -### Installation # Installation of Simple Authenticator ## Using Makefile From 7fa1df22c074fb23e22a7f75602c061b20afd05a Mon Sep 17 00:00:00 2001 From: Sina Date: Sat, 6 Jan 2024 16:05:50 +0330 Subject: [PATCH 3/3] updated docs --- README.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/README.md b/README.md index cbed1da..2b62bb3 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,118 @@ All the operator releases are bundled and pushed to the [Snappcloud hub](https:/ cpu: 1 memory: 1Gi ``` +## Development + +### Run locally +1. Install the CRDs into the cluster: + +```sh +make install +``` + +2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running): + +```sh +make run +``` + +### Building testing image + +```shell +make docker-build IMG= +``` + +### Building the helm chart + +We use [helmify](https://github.com/arttor/helmify) to generate Helm chart from kustomize rendered manifests. To update +the chart run: + +```shell +make helm +``` + +## Usage + + +The Simple Authenticator operates through the `BasicAuthenticator` custom resource, providing a straightforward way to manage authentication credentials. + +### Creating a Basic Authenticator + +To create a `BasicAuthenticator`, apply a manifest with your customizations: + +```yaml +apiVersion: authenticator.snappcloud.io/v1alpha1 +kind: BasicAuthenticator +metadata: + name: example-basicauthenticator + namespace: simple-authenticator-test +spec: + type: "sidecar" + replicas: 2 + selector: + matchLabels: + app: my-app + serviceType: "ClusterIP" + appPort: 8080 + appService: "my-app-service" + adaptiveScale: false + authenticatorPort: 80 + credentialsSecretRef: "my-credentials-secret" +``` + +### Authentication Fields + +- `type`: Sidecar or standalone deployment. +- `replicas`: Number of replicas (optional, used in deployment mode). +- `selector`: Selector for targeting specific labels (optional, used in sidecar mode). +- `serviceType`: Service type (optional). +- `appPort`: Port where the application is running (required). +- `appService`: Name of the application service (optional). +- `adaptiveScale`: Enable or disable adaptive scaling (optional, used in deployment mode). +- `authenticatorPort`: Port for the authenticator (required). +- `credentialsSecretRef`: Reference to the credentials secret (optional). + +### Authenticator Modes + +The Simple Authenticator offers two distinct operational modes to cater to different architectural needs in a Kubernetes environment: Deployment Mode and Sidecar Mode. + +#### Deployment Mode Configuration + +- __Application Service and Port__: Target application's service and port. +- __Authenticator Port__: Port for NGINX deployment to listen to. +- __Adaptive Scaling__: Automatic scaling based on number of pods of targeted service. +- __Replicas__: Number of NGINX deployment replicas. + +#### Sidecar Mode Configuration + +- __Application Port__: Application's port within the pod. +- __Authenticator Port__: Port for NGINX sidecar to listen to. +- __Selector__: Targets specific pod(s) for adding the NGINX sidecar. + +#### Trade-offs Between Deployment and Sidecar Modes + +Deployment Mode is preferable for scenarios requiring clear separation between the authentication layer and application, and is more scalable for environments with many pods. Sidecar Mode, on the other hand, is suited for scenarios where simplicity, reduced latency, and tight integration between the application and the authentication layer are priorities, albeit at the cost of increased resource consumption per pod. + +### Credential Format + +Secrets specified in `credentialsSecretRef` must contain `username` and `password` fields. If not correctly formatted, the secret will be rejected. Secrets must reside in `BasicAuthenticator`'s namespace. + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: my-credentials-secret + namespace: simple-authenticator-test +type: Opaque +stringData: + username: + password: +``` + +### Automatic Credential Generation + +If no `credentialsSecretRef` is set, a secret with a random username and password will be automatically generated. + ## Contributing Contributions are warmly welcomed. Feel free to submit issues or pull requests.