Verificando autenticación…

Skip to main content

Wrapper Utils Resources

Purpose and Scope​

This project, wrapper-utils-resources, has as its main purpose to provide the configurations and templates required to deploy gsuite-auth-wrapper in Google Kubernetes Engine (GKE) environments. The gsuite-auth-wrapper acts as an authentication proxy that allows securing applications through G Suite authentication.

The scope of this project includes:

  • Definition of Kubernetes manifests (Deployment, Service, ConfigMap) for gsuite-auth-wrapper using ERB templates.
  • Management of environment-specific configurations (development, integration, production) through YAML files.
  • Integration with Jenkins pipelines for automated deployment using Krane.

This project does not contain the gsuite-auth-wrapper source code itself, but rather the resources for its deployment and configuration.

Architecture​

The project is designed to deploy gsuite-auth-wrapper as a component within a GKE cluster. The architecture is based on:

  1. Google Kubernetes Engine (GKE): Container orchestration platform where the wrapper is deployed.
  2. gsuite-auth-wrapper: A Docker container that handles G Suite authentication. It is deployed as a Pod in Kubernetes.
  3. ConfigMaps: To manage application and environment configuration.
  4. Kubernetes Secrets: To manage sensitive information such as G Suite service account credentials.
  5. Kubernetes Service: To expose gsuite-auth-wrapper within the cluster.

The deployment.yaml.erb defines a Deployment that manages the gsuite-auth-wrapper Pods and a ClusterIP Service for internal communication.

(Note: Confluence may require a plugin to render Mermaid diagrams. Alternatively, link to an image of the diagram.)

Link to Architecture Diagram (if available externally)

Technologies and Dependencies​

  • Container Orchestration: Google Kubernetes Engine (GKE)
  • Containerization: Docker (for the gsuite_auth_wrapper image)
  • Continuous Integration/Continuous Deployment (CI/CD): Jenkins
    • Pipeline: pipelineLatam("gke-krane-deploy")
    • Deployment tool: Krane
  • Template Language: ERB (Embedded Ruby) for Kubernetes manifests.
  • Configuration Format: YAML
  • Version Control: Git (GitLab)
  • Authentication: G Suite

Local Configuration​

This project consists mainly of configuration files and deployment templates, so there is no local "application execution". Local configuration focuses on obtaining and understanding the code.

Prerequisites​

  • Git installed.
  • Access to the project repository on GitLab.
  • (Optional) Ruby installed if you want to pre-process ERB templates locally (normally done by the pipeline).
  • (Optional) kubectl configured if you want to interact with a GKE cluster.

Configuration Steps​

  1. Clone the repository: Follow the steps below

  2. Explore the project structure:

    • deploy/gke/deployment.yaml.erb: Main Kubernetes manifest template.
    • deploy/env/: Contains YAML files (dev.yaml, intg.yaml, prod.yaml) with environment-specific configurations.
    • Jenkinsfile: Defines the deployment pipeline.

Deployment​

Deployment of this project is performed through a Jenkins pipeline that uses Krane to apply the Kubernetes manifests to the corresponding GKE cluster.

Jenkins Pipeline​

The Jenkinsfile defines the pipeline to use:

#!/usr/bin/env groovy

pipelineLatam("gke-krane-deploy")

This pipeline is responsible for:

  1. Fetching the source code.
  2. Processing the deployment.yaml.erb template with environment and pipeline variables (e.g., <%= environment %>, <%= git_commit %>).
  3. Applying the generated manifests to the GKE cluster using Krane.

Per-Environment Configuration​

The files in deploy/env/ specify the gsuite_auth_wrapper image version for each environment:

  • deploy/env/dev.yaml: 
    gsuite_auth_wrapper: us-docker.pkg.dev/pipeline-corporativo/application-develop/ltmdev/gsuite-auth-wrapper:12
  • deploy/env/intg.yaml: 
    gsuite_auth_wrapper: us-docker.pkg.dev/pipeline-corporativo/application-develop/ltmdev/gsuite-auth-wrapper:12
  • deploy/env/prod.yaml: 
    gsuite_auth_wrapper: us-docker.pkg.dev/pipeline-corporativo/component-images/gsuite-auth-wrapper:201

These configurations are used by the pipeline to select the correct gsuite_auth_wrapper image during deployment.

API Endpoints​

This project itself does not define an API. It deploys gsuite-auth-wrapper, which exposes an interface for authentication. The Kubernetes service created by this project is:

  • Service Name: gsuite-auth-wrapper-acl
  • Type: ClusterIP
  • Service Port: 80
  • Container Port (targetPort): 8080

Any API exposed by gsuite-auth-wrapper will be accessible through this service on port 8080 within the cluster. For specific details about the gsuite-auth-wrapper API, refer to its dedicated documentation.

Specific Components​

gsuite-auth-wrapper​

This is the main component that is deployed.

  • General Configuration: Defined in deploy/gke/deployment.yaml.erb.
  • Docker Image: Specified per environment in the deploy/env/*.yaml files. Example: us-docker.pkg.dev/pipeline-corporativo/application-develop/ltmdev/gsuite-auth-wrapper:12
  • Environment Variables:
    • ENVIRONMENT: Current environment (e.g., dev, intg, prod).
    • APPLICATION: Owner application name (injected as <%= owner_name %>).
    • IS_PROD_DEPLOY: Boolean indicating whether it is a production deployment.
    • SERVICE_ACCOUNT: G Suite service account ID (from secret gsuite-account-id).
    • SERVICE_USER: G Suite service account user (from secret gsuite-account-user).
    • SERVICE_PRIVATE_KEY: Path to the service account private key file (/secrets/gsuite/gsuite-account).
  • Secret Mounts:
    • The Kubernetes secret gsuite-account is mounted at /secrets/gsuite inside the container, which must contain the gsuite-account key with the private key JSON.
  • Ports: Exposes port 8080 for HTTP traffic.

Fragment from deployment.yaml.erb for the container:

containers:
  - name: gsuite-auth
    image: "<%= gsuite_auth_wrapper %>" # Environment variable
    imagePullPolicy: IfNotPresent
    envFrom:
      - configMapRef:
          name: "utils-<%= environment %>-configmap"
    ports:
      - containerPort: 8080
        name: http
    env:
      - name: SERVICE_ACCOUNT
        valueFrom:
          secretKeyRef:
            name: gsuite-account-id
            key: gsuite-account-id
    # ... other variables ...
    volumeMounts:
      - name: gsuite-account
        mountPath: /secrets/gsuite
        readOnly: true

Deployment Configuration (ERB)​

The deploy/gke/deployment.yaml.erb file is a Ruby ERB template that generates Kubernetes manifests. It uses variables injected by the deployment pipeline, such as:

  • <%= environment %>: The deployment environment (dev, intg, prod).
  • <%= owner_name %>: Owner or application name.
  • <%= git_commit %>: Git commit hash.
  • <%= build_id %>: Jenkins build ID.
  • <%= gsuite_auth_wrapper %>: Docker image URL of the wrapper.
  • <%= is_prod_deploy %>: Boolean indicating whether it is a production deployment.

Testing​

This project focuses on infrastructure as code for deploying gsuite-auth-wrapper. Specific tests for this project would focus on:

  • ERB Template Validation: Ensuring templates generate valid YAML.
  • Deployment Tests (Dry-run): Verifying that krane deploy can correctly interpret the manifests.
  • Post-Deployment Integration Tests: Verifying that gsuite-auth-wrapper deploys correctly and is accessible in the cluster.

Functional tests of gsuite-auth-wrapper itself are outside the scope of this project and should be covered by the team developing that wrapper.

Currently, no automated test scripts are included in this repository.

Security Considerations​

  • Credential Management: G Suite service account credentials (gsuite-account, gsuite-account-id, gsuite-account-user) must be managed securely as Kubernetes Secrets. They should never be stored directly in the Git repository.
  • Access Tokens: Avoid committing personal access tokens (PAT) or API keys in repository configuration files (such as .git/config). These should be managed through CI/CD system environment variables or secure local configurations.
  • Docker Images: Use images from trusted sources and specific versions (avoid latest). Images are obtained from us-docker.pkg.dev, a private Google Cloud registry, which is a good practice.
  • Principle of Least Privilege: The G Suite service account used by the wrapper should have only the permissions strictly necessary.
  • Network Policies: Consider implementing Kubernetes Network Policies to restrict traffic to and from gsuite-auth-wrapper pods.