kubes 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26abdb16aa89e6a5c34aefee8430ee36e7444bb387b2bd85c4327d6f07afc038
-  data.tar.gz: 8513c5be9f224cf0081f70197390f5d55eda823c2d1b46d1c1f81d82d9e44460
+  metadata.gz: 32e7414b0e237ec67d21e06089571c57671f5ec2fb946eb89a1b2220bc1ba87d
+  data.tar.gz: 76d393eee8b25ee806ca455efe521d4a690795a1f94690d16ba39a1a0dd05d4c
 SHA512:
-  metadata.gz: 972853cd07d7a56344f8575c4c977f60cb72156a434b0589c99b311e3383f9ed30d218baf3caff7b83ee33881ae45eda496beb13935fae86c4b707bcf342de95
-  data.tar.gz: 7ada5c671ac68171034c83c56f0c535f0e33ca27aa63da9b8d96215670e7541416d4714d7151496f87cea17acc781c40ea62986d390456f7475e394f226871c6
+  metadata.gz: 4e5a7c052aaae9e0893293a9862979502f7bba65465d189691647ee5f4a4786c3e166c5e6ad2c908d72c3586a64db153253fe4e8f109fd278570c007d9ad6c53
+  data.tar.gz: ea95f2f305b03a32f2283ca103a4b69914229a238ace8527cea56898af33b7b15f563d8cc5041279758c98c9150e713a03b5acb96b08d789202c966ba34ecc03

data/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 This project *loosely tries* to adhere to [Semantic Versioning](http://semver.org/), even before v1.0.
 
+## [0.5.0]
+- #34 Generators, docker_image helper, check project, also write full.yaml #34
+- new generators: docs: https://kubes.guru/docs/generators/
+- `docker_image` helper. deprecated `built_image`. `config.image` option support.
+- check_project: check within a Kubes project
+- job dsl
+- kubes compile: auto run docker build and push when if needed
+- also write .kubes/output/full.yaml
+
+## [0.4.7]
+- #33 improve switch context: earlier and only when needed
+
+## [0.4.6]
+- #32 custom helpers support
+
+## [0.4.5]
+- #31 kubes AWS helpers
+
+## [0.4.4]
+- #30 friendly message for rendered erb yaml and dsl errors
+- fix backtrace_reject pattern
+
 ## [0.4.3]
 - #29 fix edge case when user provides hook on option for non-kubectl hooks
 

data/docs/_docs/config/reference.md

@@ -6,6 +6,7 @@ Name | Description | Default
 ---|---|---
 auto_prune | Prune and delete old hashed resources like Secret and ConfigMap. | true
 builder | What docker build command to use. Can use `docker` or `gcloud` to build the Docker image. | docker
+image | Set a prebuilt Docker image to use. This is optional. Usually, you want to build an image from the Dockerfile.  Setting this will change the `docker_image` helper to use a predefined image. See: [Docker Image]({% link _docs/intro/docker-image.md %}) | nil
 kubectl.context | What kubectl context to auto-switch to. | nil
 kubectl.context_keep | Whether or not to keep the context switched | true
 kubectl.exit_on_fail.apply  | Whether or not continue if the `kubectl apply` fails. Note, can use `KUBES_EXIT_ON_FAIL=0` env var to set to false. | true

data/docs/_docs/config/skip.md

@@ -20,7 +20,7 @@ spec:
     spec:
       containers:
       - name: cleanup
-        image: <%= built_image %>
+        image: <%= docker_image %>
         command: ["bin/cleanup.sh"]
       restartPolicy: Never
 ```

data/docs/_docs/dsl/multiple-resources.md

@@ -51,13 +51,13 @@ You can also use a block form to create multiple resources.  You name the resour
 deployment "demo-web" do
   labels(role: "web")
   replicas 1
-  image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+  image docker_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
 end
 
 deployment "demo-web-2" do
   labels(role: "web")
   replicas 1
-  image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+  image docker_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
 end
 ```
 
@@ -70,7 +70,7 @@ You can also mix and matched resources. When you use the block form, the file na
 deployment "demo-web" do
   labels(role: "web")
   replicas 1
-  image built_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
+  image docker_image # IE: user/demo:kubes-2020-06-13T19-55-16-43afc6e
 end
 
 service "demo-web" do

data/docs/_docs/dsl/resources/job.md

@@ -0,0 +1,62 @@
+---
+title: Job
+categories: dsl
+---
+
+## Example 1
+
+Here's an example of an job.
+
+.kubes/resources/migrate/job.rb
+
+```ruby
+name "<%= app %>"
+image(docker_image)
+```
+
+Produces:
+
+.kubes/output/migrate/job.yaml
+
+```yaml
+---
+apiVersion: batch/v1
+kind: Job
+metadata:
+  name: demo
+  labels:
+    app: demo
+  namespace: demo-dev
+spec:
+  template:
+    metadata:
+      labels:
+        app: demo
+    spec:
+      containers:
+      - image: 111111111111.dkr.ecr.us-west-2.amazonaws.com/demo:kubes-2020-10-26T20-25-43
+        name: demo
+```
+
+## DSL Methods
+
+Here's a list of more common methods:
+
+job.spec.template.spec.containers fields:
+
+* args
+* command
+* env
+* envFrom
+* image
+* imagePullPolicy
+* lifecycle
+* livenessProbe
+* containerName
+* ports
+* readinessProbe
+* volumeDevices
+* volumeMounts
+* workingDir
+
+{% include dsl/methods.md name="job" %}

data/docs/_docs/extra-env/dsl.md

@@ -14,7 +14,7 @@ labels(role: "web")
 namespace with_extra("default")
 
 replicas 1
-image built_image # IE: user/demo-web:kubes-2020-06-13T19-55-16-43afc6e
+image docker_image # IE: user/demo-web:kubes-2020-06-13T19-55-16-43afc6e
 ```
 
 .kubes/resources/web/service.rb
@@ -50,7 +50,7 @@ labels(app: name, extra: extra)
 namespace "default"
 
 replicas 1
-image built_image # IE: user/demo-web:kubes-2020-06-13T19-55-16-43afc6e
+image docker_image # IE: user/demo-web:kubes-2020-06-13T19-55-16-43afc6e
 ```
 
 .kubes/resources/web/service.rb

data/docs/_docs/extra-env/yaml.md

@@ -28,7 +28,7 @@ spec:
         app: demo
     spec:
       containers:
-      - image: <%= built_image %>
+      - image: <%= docker_image %>
         name: demo-web
 ```
 

data/docs/_docs/generators.md

@@ -0,0 +1,41 @@
+---
+title: Generators
+---
+
+Kubes ships with a few generators to help you get building with Kubernetes quickly.  The generated  starter YAML should be modified and customized for your needs.
+
+## Examples
+
+Here are a few examples:
+
+    $ kubes new ingress
+          create  .kubes/resources/web/ingress.yaml
+    $ kubes new service_account
+          create  .kubes/resources/shared/service_account.yaml
+    $
+
+Use `-h` to see the cli options:
+
+    kubes new -h
+
+## Supported Resources
+
+Here's a list of some of the supported resources.
+
+    backend_config
+    config_map
+    daemon_set
+    deployment
+    ingress
+    job
+    managed_certificate
+    namespace
+    network_policy
+    pod
+    role_binding
+    role
+    secret
+    service_account
+    service
+
+Refer to the [source code](https://github.com/boltops-tools/kubes/blob/master/lib/templates/new/yaml) to all the resources that the generator supports.

data/docs/_docs/helpers.md

@@ -6,8 +6,8 @@ Kubes provides some helper methods to help write Kubernetes YAML files.  Here's
 
 Helper | Description
 --- | ---
-built_image | Method refers to the latest Docker image built by Kubes. This spares you from having to update the image manually in the deployment resource.
-decode64 | Basey64d decode a string.
+decode64 | Basey64 decode a string.
+docker_image | Method refers to the latest Docker image built by Kubes. This spares you from having to update the image manually in the deployment resource. Note, this can be overridden with the `--image` cli option or the `Kubes.config.image` setting. See: [Docker Image]({% link _docs/intro/docker-image.md %})
 dockerfile_port	| Exposed port extracted from the Dockerfile of the project.
 encode64 | Basey64 encode a string. Also available as `base64` method.
 extra | The `KUBES_EXTRA` value.
@@ -17,4 +17,11 @@ Here's also the source code with most of the helpers: [helpers.rb](https://githu
 
 ## DSL Specific Methods
 
-Each DSL resource has it's own specific methods. Refer to the [DSL Docs]({% link _docs/dsl.md %}) for their methods.
+Each DSL resource has it's own specific methods. Refer to the [DSL Docs]({% link _docs/dsl.md %}) for their methods.
+
+## Provider Helpers
+
+There are also provider-specific helpers:
+
+* [AWS Helpers]({% link _docs/helpers/aws.md %})
+* [Google Helpers]({% link _docs/helpers/google.md %})

data/docs/_docs/helpers/aws.md

@@ -0,0 +1,15 @@
+---
+title: AWS Helpers
+---
+
+List of AWS helpers:
+
+{% assign docs = site.docs | where: "categories","helpers-aws" %}
+{% for doc in docs -%}
+  * [{{ doc.nav_text }}]({{ doc.url }})
+{% endfor %}
+
+## Notes
+
+* By default, `KubeGoogle.logger = Kubes.logger`. This means, you can set `logger.level = "debug"` in `.kubes/config.rb` to see more details.
+* The AWS helpers are provided by the [boltops-tools/kubes_aws](https://github.com/boltops-tools/kubes_aws) library.

data/docs/_docs/helpers/aws/iam-role.md

@@ -0,0 +1,91 @@
+---
+title: AWS IAM Role
+nav_text: IAM Role
+categories: helpers-aws
+---
+
+You can automatically create the IAM Role associated with the Kubernetes Service Account, covered in [Introducing fine-grained IAM roles for service accounts](https://aws.amazon.com/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/).
+
+Here's a Kubes hook that creates an IAM Role:
+
+.kubes/config/hooks/kubes.rb
+
+```ruby
+iam_role = KubesAws::IamRole.new(
+  app: "demo",
+  namespace: "demo-#{Kubes.env}", # defaults to APP-ENV when not set. IE: demo-dev
+  managed_policies: ["AmazonS3ReadOnlyAccess", "AmazonSSMReadOnlyAccess"], # defaults to empty when not set
+  inline_policies: [:secrets_read_only], # See Secrets Read Only Inline Policy at the bottom
+)
+before("apply",
+  label: "create iam role",
+  execute: iam_role,
+)
+KubesAws::IamRole.role_arn = iam_role.arn # used in .kubes/resources/shared/service_account.yaml
+```
+
+The corresponding Kubernetes Service account looks like this:
+
+.kubes/resources/shared/service_account.yaml
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  annotations:
+    eks.amazonaws.com/role-arn: <%= KubesAws::IamRole.role_arn %>
+  name: demo
+  labels:
+    app: demo
+```
+
+The role policy permissions are currently always added to the existing permissions. So removing roles that were previously added does not remove them.
+
+IamRole#initialize options:
+
+Variable | Description | Default
+---|---|---
+app | The app name. It's used to set other variables conventionally. This is required. | nil
+ksa | The Kubernetes Service Account name. The conventional name is APP. IE: demo | APP
+namespace | The Kubernetes namespace. Defaults to the APP-ENV. IE: demo-dev. | APP-ENV
+policies | IAM policies to add. This adds permissions to the IAM Role. | []
+role_name | The IAM Role name. The conventional name is APP-ENV. IE: demo-dev. | APP-ENV
+
+## OpenID Connect Provider
+
+The `KubesAws::IamRole` class also automatically creates the OpenID Connect Provider if it doesn't already exist.
+
+## Secrets Read-Only Inline Policy
+
+Note the the `:secrets_read_only` is a way to generate an Inline Policy that represents read-only access for Secrets. Kubes does this since there's no managed policy for this yet. For example:
+
+```ruby
+inline_policies: [:secrets_read_only]
+```
+
+Is the same as:
+
+```ruby
+inline_secrets_read_only = {
+  policy_document: {
+    Version: "2012-10-17",
+    Statement: {
+      Effect: "Allow",
+      Action: [
+        "secretsmanager:Describe*",
+        "secretsmanager:Get*",
+        "secretsmanager:List*"
+      ],
+      Resource: "*"
+    }
+  },
+  policy_name: "SecretsReadOnly",
+}
+iam_role = KubesAws::IamRole.new(
+  app: "rails",
+  cluster: "dev-cluster",
+  namespace: "rails-#{Kubes.env}", # defaults to APP-ENV when not set. IE: rails-dev
+  managed_policies: ["AmazonS3ReadOnlyAccess", "AmazonSSMReadOnlyAccess"], # defaults to empty when not set
+  inline_policies: [inline_secrets_read_only],
+)
+```

data/docs/_docs/helpers/aws/secrets.md

@@ -0,0 +1,129 @@
+---
+title: AWS Secrets
+nav_text: Secrets
+categories: helpers-aws
+---
+
+## Simple Values
+
+For example if you have these secret values:
+
+    $ aws secretsmanager get-secret-value --secret-id demo/dev/db_user | jq '.SecretString'
+    user
+    $ aws secretsmanager get-secret-value --secret-id demo/dev/db_pass | jq '.SecretString'
+    pass
+
+Set up a [Kubes hook](https://kubes.guru/docs/config/hooks/kubes/).
+
+.kubes/config/hooks/kubes.rb
+
+```ruby
+secrets = KubesAws::Secrets.new(upcase: true, prefix: "demo/dev/")
+before("compile",
+  label: "Get secrets from AWS Secrets Manager",
+  execute: secrets,
+)
+```
+
+Then set the secrets in the YAML:
+
+.kubes/resources/shared/secret.yaml
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: demo
+  labels:
+    app: demo
+data:
+<% KubesAws::Secrets.data.each do |k,v| -%>
+  <%= k %>: <%= base64(v) %>
+<% end -%>
+```
+
+This results in AWS secrets with the prefix the `demo/dev/` being added to the Kubernetes secret data.  The values are automatically base64 encoded. Produces:
+
+.kubes/output/shared/secret.yaml
+
+```yaml
+metadata:
+  namespace: demo
+  name: demo-2a78a13682
+  labels:
+    app: demo
+apiVersion: v1
+kind: Secret
+data:
+  db_pass: dGVzdDEK
+  db_user: dGVzdDIK
+```
+
+## JSON Values
+
+For example if you have these secret values:
+
+    $ aws secretsmanager get-secret-value --secret-id demo/dev/k2 | jq '.SecretString'
+    {\"a\":1,\"b\":2}"
+
+Set up a [Kubes hook](https://kubes.guru/docs/config/hooks/kubes/).
+
+.kubes/config/hooks/kubes.rb
+
+```ruby
+secrets = KubesAws::Secrets.new(prefix: "rails/dev/")
+before("compile",
+  label: "Get secrets from AWS Secrets Manager",
+  execute: secrets,
+)
+```
+
+Then set the secrets in the YAML:
+
+.kubes/resources/shared/secret.yaml
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: demo
+  labels:
+    app: demo
+data:
+<% k2 = JSON.load(KubesAws::Secrets.data["k2"]) %>
+  a: <%= base64(k2["a"]) %>
+  b: <%= base64(k2["b"]) %>
+```
+
+Produces:
+
+```yaml
+metadata:
+  namespace: demo-dev
+  name: demo-a4cd604a95
+  labels:
+    app: demo
+apiVersion: v1
+kind: Secret
+data:
+  a: MQ==
+  b: Mg==
+```
+
+## Variables
+
+These environment variables can be set:
+
+Name | Description
+---|---
+AWS_SECRET_PREFIX | Prefixed used to list and filter AWS secrets. IE: `demo/dev/`.
+
+Secrets#initialize options:
+
+Variable | Description | Default
+---|---|---
+base64 | Automatically base64 encode the values. | false
+upcase | Automatically upcase the Kubernetes secret data keys. | false
+prefix | Prefixed used to list and filter AWS secrets. IE: `demo/dev/`. Can also be set with the `AWS_SECRET_PREFIX` env variable. The env variable takes the highest precedence. | nil
+
+{% include helpers/base64.md %}