kubernetes_helper 1.13.2 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9257b84ef107ed3b39ce537325de4357b348023becbf0f14fcf761bdf652d3f0
-  data.tar.gz: 77abef0bae873a41b1ed2fce90d49c55f07b43acbef6b578ae9b0e7f45716893
+  metadata.gz: 33da4492b4f95cbd8a47c55b8b2449f99b0c2224e7b52017e12d95c50efa2414
+  data.tar.gz: d7a12f66bfbd86a252acd1d6e57978a1f73497f7578cc0f9c484b1c4f93983a4
 SHA512:
-  metadata.gz: f2798fb189f4e2ab77507dd8095d0f2741ef70d163a03d98f734f6d4772395b7521c77aed051a97a9d5241fca3ef0d8cdc0d19c4ea430ea81ed0af7e4d9f89ca
-  data.tar.gz: 4446e493e3cb37ec030d99e1ede09738bce1e8cd17f16f35c95ded98c1a18213cb7997d03d7b3e6c6c59d273fcf5468a09cd709aaaca6f87859bfa5f44d419f5
+  metadata.gz: 10cabcc986c70e54adf560d32c834c6421958fdbf0dcaf1d991e9a1bd994cb34c4f9dd126261abc638c2bff1dd899e776840c83da8887c10e0975607cd3641b9
+  data.tar.gz: 306780df8402e223537b35fc02edaf7f8157b91aa7c8ce0512d38e49e46bcb529a3da06eb495fd0ea167e076423f6cd952ed5a5b9d2dbcf5bf14b34a627d561c

data/README.md

@@ -3,69 +3,30 @@
 This gem is a helper to manage easily Kubernetes settings for GCloud (easy customization for other cloud services) where configuring and deploying a new application can be done in a couple of minutes.
 Configuration and customization can be done for multiple environments and at any level which permits to deploy simple and complex applications.
 
-## Installation
-```bash
-cd my_app/
-gem install kubernetes_helper -v '~> 1.0'
-kubernetes_helper generate_templates
-```
-Note: Requires ruby 1.7+     
-
-## Configuration
-- Edit `.kubernetes/settings.rb` and enter or replace all settings with the valid ones
-- For special applications where default configurations are not enough, you can do the following: 
-    - Download the corresponding template from [lib/templates](lib/templates)
-    - Put it inside `.kubernetes` folder
-    - Customize based on your needs (You can add or use your custom variables from `settings.rb`)    
-    Note: The local template will be used instead of the default.
-
-## Deployment
-Once you generated the basic templates, it comes with the corresponding [readme.md](/lib/templates/README.md) which includes all the steps to deploy your application.
-
-## API
-- Run any kubernetes document    
-  `DEPLOY_ENV=<env name> kubernetes_helper run_deployment "<document name>" "<bash command>"`    
-  Evaluates the kubernetes document with the following details:
-  - Supports for `- documents` to include multiple documents in a file and share yml variables between them (Sample: `lib/templates/deployment.yml#1`)
-  - Replaces all setting values based on `DEPLOY_ENV`
-  - Supports for secrets auto importer using `import_secrets: ['secrets.yml', '<%=secrets.name%>']` (Sample: `lib/templates/deployment.yml#29`)
-  - Supports for sub templates by `include_template 'template_name.yml.erb', { my_local_var: 10 }`    
-  Sample: `DEPLOY_ENV=beta kubernetes_helper run_deployment "deployment.yml" "kubectl create"`
-   
-- Run kubernetes commands    
-  `DEPLOY_ENV=<env name> rake kubernetes_helper:run_command "<bash or k8s commands>"`           
-  Replaces all setting variables inside command based on `DEPLOY_ENV` and performs it as a normal bash command.             
-  Sample: `DEPLOY_ENV=beta rake kubernetes_helper:run_command "gcloud compute addresses create \#{ingress.ip_name} --global"'`    
-  
-- Run kubernetes bash scripts     
-  `DEPLOY_ENV=<env name> kubernetes_helper run_script "<script name>"`    
-  Performs the script name located inside `.kubernetes` folder or kubernetes_helper template as the second option.
-  All setting variables inside the script will be replaced based on `DEPLOY_ENV`.      
-  Sample: `DEPLOY_ENV=beta kubernetes_helper run_script "cd.sh"`
+## Steps
+1. Install the `kubernetes_helper` gem
+      ```bash
+      cd my_app/
+      gem install kubernetes_helper -v '~> 1.0'
+      ```
+      Note: Requires ruby 1.7+    
+
+2. Generate helper settings
+      ```bash
+        kubernetes_helper generate_templates
+      ```
+      Note: `.kubernetes` folder was added. For special applications where default configurations are not enough, you can do the following: 
+      - Download the required template from [lib/templates](lib/templates)
+      - Put it inside `.kubernetes` folder
+      - Customize based on your needs (You can add or use your custom variables from `settings.rb`)    
+      Note: The local template will be used instead of the default one.
+
+3. Install/setup the application on kubernetes    
+  Open [.kubernetes/README.md](lib/templates/README.md) to see the instructions (customize the file according to your project and keep it updated)
 
-- Generate templates    
-  `DEPLOY_ENV=<env name> kubernetes_helper generate_templates "<mode_or_template_name>"`     
-  Copy files based on mode (`basic|advanced`) or a specific file from templates.     
-  Sample: `DEPLOY_ENV=beta kubernetes_helper generate_templates "basic"`    
-  Sample: `DEPLOY_ENV=beta kubernetes_helper generate_templates "ingress.yml"`    
-
-When performing a script it looks first for file inside .kubernetes folder, if not exist, 
-it looks for the file inside kubernetes_helper template folder.    
 
 ## Settings API
-Below settings are used when running Continuous Deployment
-- `continuous_deployment.image_name` (String): Partial docker image url. Sample: `gcr.io/my-account/my_app_name`
-- `continuous_deployment.image_tag` (String, default 'latest'): Image tag to be used for this application
-- `continuous_deployment.project_name`: Cloud project name. Sample: `my-project-name`
-- `continuous_deployment.cluster_name`: Cluster cluster name. Sample: `my-cluster-name`
-- `continuous_deployment.cluster_region`: Cluster region name. Sample: `europe-west4-a`
-- `continuous_deployment.docker_build_cmd` (deprecated): Docker command to build the corresponding image. Sample: `build --target production -f Dockerfile `
-- `continuous_deployment.docker_cmd` (String): Docker command to build the corresponding image.      
-  Simple docker image: `docker build -f Dockerfile -t $DEPLOY_NAME .`    
-  Docker image with target: `docker build --target production -f Dockerfile -t $DEPLOY_NAME .`        
-- `continuous_deployment.update_deployment` (Boolean, default: false): If true permits to re-generate and update the k8s deployment(s) before applying the new version (new docker image) 
-
-Below settings are used when configuring the application in the k8s environment
+### Application deployment.yml
 - `deployment.name` (String): Web deployment name (Note: Underscores are not accepted). Sample: `my-app`  
 - `deployment.replicas` (Integer): Quantity of replicas. Sample: `1`
 - `deployment.replicas_range` (Array<min, max, cpu_percentage>, Optional): Defines the minimum and the maximum number of pods that could automatically be created when `CPUUtilizationPercentage` is above than defined. Sample: `[1, 3, 50]`
@@ -74,7 +35,6 @@ Below settings are used when configuring the application in the k8s environment
 - `deployment.env_vars` (Hash, optional): List of static or external env variables (Note: Not recommended for sensitive values).      
    Sample: `{ 'RAILS_ENV' => 'production' }`      
    Example for external secrets: `{ PAPERTRAIL_PORT: { name: 'common_secrets', key: 'paper_trail_port' }` will import `paper_trail_port` value from `common_secrets` yml as `PAPERTRAIL_PORT`
-  
 - `deployment.command` (String, Optional): Bash command to be used for web containers. Sample: `rails s -b 0.0.0.0`
 - `deployment.liveness_path` (String, Optional): Relative path to be used for readiness and liveness checker of the web app. Sample: `/check_liveness`
 - `deployment.custom_volumes` (Hash<name: path>, Optional): Custom volumes to be mounted. 
@@ -84,26 +44,42 @@ Below settings are used when configuring the application in the k8s environment
 - `deployment.log_folder` (String, default `/app/log`): Logs to be printed from
 - `deployment.app_port` (Integer, default 3000): Application port number
 
+### Application deployment.yml for jobs or services without internet interaction (Optional)
 - `deployment.job_name` (String, optional): Job deployment name (Note: Underscores are not accepted). Sample: `my-app-job`. Note: This deployment is created only if this value is present
 - `deployment.job_command` (String, optional): Bash command to be used for job container. Sample: `bundle exec sidekiq`
 - `deployment.job_sidekiq_alive_gem` (Boolean, default false): If true will add liveness checker settings using `sidekiq_alive_gem` (`sidekiq_alive` gem needs to be present in your Gemfile)
 - `deployment.job_services` (Array, Optional, only `job_sidekiq_alive_gem` or `job_services` is allowed): List of linux service names that are required for a healthy job container. Sample: `['sidekiq', 'cron']` 
 
-
+### Applications secrets.yml (Optional)
 - `secrets.name` (String): K8s secrets name where env vars will be saved and fetched from. Sample: `my-app-secrets`
 
+### Application service.yml (Optional)
 - `service.name`: K8s service name. Sample: `my-app-service`
 - `service.port_name` (String, default `http-port`): Http port name to connect between k8s ingress and service. Sample: `http-port`. Note: max 15 characters
 - `service.backend_port_name` (String, default `b-port`): Web backend port name to be connected between k8s service and web deployments. Sample: `b-port`. Note: max 15 characters
 
+### Application ingress.yml (Optional)
 - `ingress.name`: Name of k8s ingress for the app: Sample: `my-app-ingress`
 - `ingress.ip_name` (Optional): Static ip address is not created nor assigned if empty value. Sample: `my-app-static-ip`
-- `ingress.certificate_name` (Optional): Ssl certificate is not created nor assigned if empty value. Sample: `my-app-lets-encrypt`. Note: requires `certificate_domain` 
-- `ingress.certificate_domain` (Optional): Domain name for the certificate. Sample: `myapp.com`. Note: does not support for willcard domains
+- `ingress.certificate_name` (Deprecated): Ssl certificate is not created nor assigned if empty value. Sample: `my-app-lets-encrypt`. Note: requires `certificate_domain` 
+- `ingress.certificate_domain` (Optional): Domain name for the certificate. Sample: `myapp.com`. Note: does not support for willcard domains     
+   To register multiple domains (Certificate names will be auto-generated like `mysite-com-lets-encrypt`): `certificate_domain: ['mysite.com', 'mysite.de', 'mysite.uk']`
 
 - `cloud.name` (String, optional): Cloud service name. Default `gcloud`.  
 
-### Partials
+### Application CD (continuous deployment)
+- `continuous_deployment.image_name` (String): Partial docker image url. Sample: `gcr.io/my-account/my_app_name`
+- `continuous_deployment.image_tag` (String, default 'latest'): Image tag to be used for this application
+- `continuous_deployment.project_name`: Cloud project name. Sample: `my-project-name`
+- `continuous_deployment.cluster_name`: Cluster cluster name. Sample: `my-cluster-name`
+- `continuous_deployment.cluster_region`: Cluster region name. Sample: `europe-west4-a`
+- `continuous_deployment.docker_build_cmd` (deprecated): Docker command to build the corresponding image. Sample: `build --target production -f Dockerfile `
+- `continuous_deployment.docker_cmd` (String): Docker command to build the corresponding image.      
+  Simple docker image: `docker build -f Dockerfile -t $DEPLOY_NAME .`    
+  Docker image with target: `docker build --target production -f Dockerfile -t $DEPLOY_NAME .`        
+- `continuous_deployment.update_deployment` (Boolean, default: false): If true permits to re-generate and update the k8s deployment(s) before applying the new version (new docker image)
+
+### Gem templating partials
 - `_container_extra_settings.yml` Partial template to add custom container settings. Receives `pod` as local variable (`web` | `job` | `cloudsql` | `logs`). Sample:
   ```yaml
                <% if locals[:pod] == 'job' %>
@@ -126,18 +102,50 @@ Below settings are used when configuring the application in the k8s environment
 ```
 - `_cd_apply_images.sh` Partial template to customize the process to apply the new version (new docker image)
 
-## Templating
+### Gem templating
 When performing a command or script, the setting variables are replaced based on `DEPLOY_ENV`. 
 All these setting variable values are configured in `.kubernetes/settings.rb` which defines the values based on `DEPLOY_ENV`.     
 These setting variables use [erb](https://github.com/ruby/erb) template gem to define variable replacement and conditional blocks, and so on.
 Note: Setting variable values are referenced as an object format instead of a hash format for simplicity.
   
 
-## Sample
+### Sample
 https://owen2345.github.io/kubernetes_helper/
 
+
+## API
+- Run any kubernetes document    
+  `DEPLOY_ENV=<env name> kubernetes_helper run_deployment "<document name>" "<bash command>"`    
+  Evaluates the kubernetes document with the following details:
+  - Supports for `- documents` to include multiple documents in a file and share yml variables between them (Sample: `lib/templates/deployment.yml#1`)
+  - Replaces all setting values based on `DEPLOY_ENV`
+  - Supports for secrets auto importer using `import_secrets: ['secrets.yml', '<%=secrets.name%>']` (Sample: `lib/templates/deployment.yml#29`)
+  - Supports for sub templates by `include_template 'template_name.yml.erb', { my_local_var: 10 }`    
+  Sample: `DEPLOY_ENV=beta kubernetes_helper run_deployment "deployment.yml" "kubectl create"`
+   
+- Run kubernetes commands    
+  `DEPLOY_ENV=<env name> rake kubernetes_helper:run_command "<bash or k8s commands>"`           
+  Replaces all setting variables inside command based on `DEPLOY_ENV` and performs it as a normal bash command.             
+  Sample: `DEPLOY_ENV=beta rake kubernetes_helper:run_command "gcloud compute addresses create \#{ingress.ip_name} --global"'`    
+  
+- Run kubernetes bash scripts     
+  `DEPLOY_ENV=<env name> kubernetes_helper run_script "<script name>"`    
+  Performs the script name located inside `.kubernetes` folder or kubernetes_helper template as the second option.
+  All setting variables inside the script will be replaced based on `DEPLOY_ENV`.      
+  Sample: `DEPLOY_ENV=beta kubernetes_helper run_script "cd.sh"`
+
+- Generate templates    
+  `DEPLOY_ENV=<env name> kubernetes_helper generate_templates "<mode_or_template_name>"`     
+  Copy files based on mode (`basic|advanced`) or a specific file from templates.     
+  Sample: `DEPLOY_ENV=beta kubernetes_helper generate_templates "basic"`    
+  Sample: `DEPLOY_ENV=beta kubernetes_helper generate_templates "ingress.yml"`    
+
+When performing a script it looks first for file inside .kubernetes folder, if not exist, 
+it looks for the file inside kubernetes_helper template folder.
+
 ## TODO
 - Add one_step_configuration.sh
+- Change `include_template` into `ERB render partial`
 
 ## Contributing
 

data/lib/kubernetes_helper/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KubernetesHelper
-  VERSION = '1.13.2'
+  VERSION = '1.14.0'
 end

data/lib/templates/README.md

@@ -1,6 +1,6 @@
 # Kubernetes app configuration
 
-## Configure a new application environment
+## Cluster connection
 - Create the project on Gcloud
 - Set the project where to work on     
     `gcloud config set project my-project`
@@ -13,13 +13,14 @@
 - Use the cluster/project as default    
     `gcloud container clusters get-credentials my-cluster --zone europe-west4-a`
   
-- Install helper for the next commands    
-  `gem install kubernetes_helper`
+## App setup
+- Install kubernetes-helper (if not installed yet)    
+  `gem install kubernetes_helper`  
   
-- Verify or update k8s settings in .kubernetes/settings.rb        
-  Note: Please do not include sensitive values in this file, ENV values are recommended instead.
+- Verify or update k8s settings in `.kubernetes/settings.rb`        
+  Note: Please do not include sensitive values in this file, secrets are recommended instead.
 
-- Register shared cloudsql proxy configuration (only if not exists)    
+- Register shared cloudsql proxy configuration to connect application to the Database/Pubsub (only if it does not exist yet)    
     ```bash
     DEPLOY_ENV=beta kubernetes_helper run_command "kubectl create secret generic <%=deployment.cloud_secret_name%> --from-file=credentials.json=<path-to-downloaded/credentials.json>"
     ```
@@ -60,7 +61,67 @@
     # You can start accessing to the app using the generated ip address
     # `kubectl get ManagedCertificate` # to see the status of ssl provisionning
     ```
+- Update your domain to point to the new generated ip address (if required) and visit the domain or the ip address to see your application.     
+  Note: The domain name propagation can take some time before pointing to the new ip address.     
+  Note2: If the application shows "404 not found", check the deployment/pods status by: `kubectl get pods`    
+  Note3: If the pod error is `ImagePullBackOff`, it is because the application docker image is missing. 
+  You can deploy your application via github actions or similar (see #Configure-continuous-deployment-for-github-actions) or do it manually (see #Deploy-application-manually)
 
+## Deploy application manually
+Run the deployment manually with:     
+```bash
+  DEPLOY_ENV=beta kubernetes_helper run_deployment 'cd.sh'
+```     
+The application image will be create and uploaded to the configured container registry (application pods should be restarted with the new docker image).      
+Visit the application url to see changes.
+
+## Configure continuous deployment for github actions
+This gem comes with continuous deployment script out of the box which can be executed with a single line of code.
+* Go to github repository settings    
+* Register a new secret variable with content downloaded from (for google cloud) https://console.cloud.google.com/iam-admin/serviceaccounts 
+    (Make sure to attach a "Editor", "Storage Admin" and "Kubernetes engine cluster admin" role to the service account)
+  ```bash
+    BETA_CLOUD_TOKEN=<secret content here>
+    PROD_CLOUD_TOKEN=<secret content here>
+  ```
+  
+* Add github workflow to automatically run deployment when merged into master or staging, something like:    
+```yml
+name: "Continuous Deployment"
+on:
+  push:
+    branches: 
+      - master
+      - staging
+
+deployment:
+  runs-on: ubuntu-latest
+  jobs:
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          ref: ${{ env.DEPLOY_BRANCH }}
+      - name: Cancel previous Workflow Actions
+        uses: styfle/cancel-workflow-action@0.6.0
+        with:
+          access_token: ${{ github.token }}
+
+      - name: Set up Cloud SDK
+        uses: google-github-actions/setup-gcloud@master
+      - uses: satackey/action-docker-layer-caching@v0.0.11
+        continue-on-error: true
+        with:
+          key: CD-docker-cache-${{ hashFiles('Dockerfile', 'Gemfile.lock') }}
+
+      #### App deployment          
+      - run: sudo gem install kubernetes_helper
+      - name: App deployment
+        env:
+          KB_AUTH_TOKEN: ${{ github.ref_name == 'master' && secrets.PROD_CLOUD_TOKEN || secrets.BETA_CLOUD_TOKEN }}
+          DEPLOY_ENV: ${{ github.ref_name == 'master' && 'production' || 'beta' }}
+        run: kubernetes_helper run_deployment 'cd.sh'
+```   
+  
 ## Apply any k8s setting changes
 - Secrets    
   Open kubernetes secrets and add/edit/remove values and then save it    
@@ -70,30 +131,4 @@
 - Other settings    
   ```bash
     DEPLOY_ENV=beta kubernetes_helper run_yml 'deployment.yml' 'kubectl apply'
-  ```
-
-## Configure continuous deployment for github actions
-* Go to github repository settings    
-* Register a new secret variable with content downloaded from https://console.cloud.google.com/iam-admin/serviceaccounts 
-    (Make sure to attach a "Editor", "Storage Admin" and "Kubernetes engine cluster admin" role to the service account)
-  ```bash
-    beta: BETA_CLOUD_TOKEN=<secret content here>
-    production: PROD_CLOUD_TOKEN=<secret content here>
-  ```
-  
-* Add action to run deployment:    
-  ```bash
-    env:
-      KB_AUTH_TOKEN: secrets.BETA_CLOUD_TOKEN
-    run: DEPLOY_ENV=beta kubernetes_helper run_deployment 'cd.sh'
-  ``` 
-  
-* Sample:    
-  ```yml
-  - run: sudo gem install kubernetes_helper
-  - name: Staging deployment
-    env: # Env variable saved in github that contains gcloud credential (json format)
-      KB_AUTH_TOKEN: ${{ secrets.BETA_GOOGLE_AUTH }}
-    run: DEPLOY_ENV=beta kubernetes_helper run_deployment 'cd.sh'
-    if: ${{ !contains(fromJson('["main", "master"]'), env.DEPLOY_BRANCH) }}
-  ```   
+  ```  

data/lib/templates/certificate.yml

@@ -1,7 +1,12 @@
+# locals: { domains: Hash(domain => cert_name) }
+<% locals[:domains].each do |domain, cert_name| %>
 apiVersion: networking.gke.io/v1beta1
 kind: ManagedCertificate
 metadata:
-  name: '<%=ingress.certificate_name%>'
+  name: '<%= cert_name %>'
 spec:
-  domains: # does not support for willcard domains
-    - '<%= ingress.domain_name || ingress.certificate_domain %>'
+  domains: # does not support for willcard domains nor multiple domains
+    - '<%= domain %>'
+
+---
+<% end %>

data/lib/templates/ingress.yml

@@ -1,5 +1,9 @@
-<% if ingress.certificate_name %>
-<%= include_template "certificate.yml" %>
+<%
+  domains = Array(ingress.domain_name || ingress.certificate_domain)
+  domains = domains.map { |domain| cert_name = "#{domain.downcase.gsub(/[^0-9A-Za-z]/, '-')}-lets-encrypt"; domains.count > 1 ? [domain, cert_name] : [domain, ingress.certificate_name || cert_name] }.to_h
+%>
+<% if ingress.certificate_domain %>
+<%= include_template "certificate.yml", { domains: domains } %>
 <% end %>
 
 ---
@@ -17,8 +21,8 @@ metadata:
     kubernetes.io/ingress.global-static-ip-name: "<%=ingress.ip_name%>"
     <% end %>
 
-    <% if ingress.certificate_name %>
-    networking.gke.io/managed-certificates: '<%=ingress.certificate_name%>'
+    <% if ingress.certificate_domain %>
+    networking.gke.io/managed-certificates: '<%= domains.values.join(", ") %>'
     <% end %>
 
 spec:

data/lib/templates/settings.rb

@@ -26,7 +26,6 @@ settings = {
   ingress: {
     name: "#{app_name}-ingress",
     ip_name: "#{app_name}-static-ip", # nil if static ip is not necessary
-    certificate_name: "#{app_name}-lets-encrypt", # nil if ssl is not required
     certificate_domain: is_production ? 'myapp.com' : 'beta.myapp.com' # nil if domain is not required
   },
   continuous_deployment: {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kubernetes_helper
 version: !ruby/object:Gem::Version
-  version: 1.13.2
+  version: 1.14.0
 platform: ruby
 authors:
 - owen2345
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-03-18 00:00:00.000000000 Z
+date: 2022-03-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: erb