Merge pull request #10 from jumppad-labs/c-docs-updates

C docs updates
jumppad-labs · Aug 22, 2023 · ee039b7 · ee039b7
2 parents c0d588d + 9d72c25
commit ee039b7
Show file tree

Hide file tree

Showing 8 changed files with 317 additions and 45 deletions.
diff --git a/src/pages/docs/resources/build/index.mdx b/src/pages/docs/resources/build/index.mdx
@@ -9,7 +9,7 @@ this feature to build container images that can be started directly using the `c
 or copied to `nomad` or `kubernetes`.
 
 In addition to building containers, `build` blocks can be used to build application code in a docker
-container the product of which can be copied to the local file system using the optional `output` stanza.
+container, the product of which can be copied to the local file system using the optional `output` stanza.
 </Intro>
 
 ## Properties

diff --git a/src/pages/docs/resources/copy/index.mdx b/src/pages/docs/resources/copy/index.mdx
@@ -1,7 +1,36 @@
 # Copy `copy`
 
 <Intro>
-Documentation is work in progress, please see the old documentation at:
+The `copy` resource allows files and directories to be copied
+from one location to another.
+</Intro>
 
-https://shipyard.run/docs/resources/copy
-</Intro>
+## Properties
+
+<Properties>
+  <Property name="source" type="string" required="true" value=""> 
+    Source file or directory.
+  </Property>
+  <Property name="destination" type="string" required="true" value=""> 
+    Destination file or directory.
+  </Property>
+  <Property name="permissions" type="string" required="false" value="0777"> 
+    Unix file permissions to apply to coppied files and direcories.
+  </Property>
+  <Property name="copied_files" type="[]string" required="optional" value="" readonly> 
+    List of the full paths of copied files.
+  </Property>
+</Properties>
+
+<MetaProperties/>
+
+## Examples
+
+### Copies files from ./myfiles and sets read / write permissions
+
+```hcl
+resource "copy" "myfiles" {
+  source = "./myfolder"
+  destination = "./mydestination"
+  permissions = "0666"
+```
diff --git a/src/pages/docs/resources/helm/index.mdx b/src/pages/docs/resources/helm/index.mdx
@@ -3,27 +3,132 @@ import MetaProperties from "../shared/meta.mdx"
 # Helm `helm`
 
 <Intro>
-The `helm` resource allows Helm charts to be provisioned to `k8s_cluster` resources.
-
-Documentation is work in progress, please see the old documentation at:
-
-https://shipyard.run/docs/resources/helm
+The `helm` resource allows Helm charts to be provisioned to `k8s_cluster` 
+resources.
 </Intro>
 
 ## Properties
 
 <Properties>
-  <Property name="cluster" type="string" required="true" value="" readonly> 
-    Text
+  <Property name="cluster" type="k8s_cluster" required="true" value=""> 
+    A reference to a kubernetes clusters to apply the chart to. Jumppad
+    waits until the referenced cluster is healthy before attempting t
+    apply any charts.
+
+    ```hcl
+    resource "helm" "consul" {
+      cluster = resource.k8s_cluster.k3s
+    }
+    ```
+  </Property>
+
+  <Property name="repository" type="#helm_repository" required="optional" value=""> 
+    The details for the Helm chart repository where the chart exists. If this
+    property is not specifed, the chart location is assumed to be either a local
+    directory or Git reference. 
+  </Property>
+
+  <Property name="chart" type="string" required="true" value=""> 
+    The name of the chart within the repository, or a souce
+    such as a git repository, URL, or file path where the chart
+    file exist.
+  </Property>
+
+  <Property name="version" type="string" required="optional" value=""> 
+    Semver of the chart to install, only used when `repository` is
+    specified.
+  </Property>
+
+  <Property name="values" type="string" required="optional" value=""> 
+    File path to a valid Helm values file to be used when applying the config.
+
+    ```hcl
+    resource "helm" "mychart" {
+      values = "./values.yaml"
+    }
+    ```
+  </Property>
+
+  <Property name="values_string" type="map[string]string" required="optional" value=""> 
+    Map containing helm values to apply with the chart.
 
     ```hcl
-    code
+    resource "helm" "mychart" {
+      values_string = {
+        "global.storage" = "128Mb"
+      }
+    }
     ```
   </Property>
+
+  <Property name="namespace" type="string" required="optional" value="default"> 
+    Kubernetes namespace to apply the chart to.
+  </Property>
+
+  <Property name="create_namespace" type="boolean" required="optional" value="false"> 
+    If the namespace does not exist, should the helm resource attempt to create it.
+  </Property>
+
+  <Property name="skip_crds" type="boolean" required="optional" value="false"> 
+    If the chart defines custom resource definitions, should these be ignored.
+  </Property>
+
+  <Property name="retry" type="int" required="optional" value="1"> 
+    Enables the ability to retry the installation of a chart.
+  </Property>
+
+  <Property name="timeout" type="string" required="optional" value="300s"> 
+    Maximum time the application phase of a chart can run before failing.
+    This duration is different to the `health_check` that runs after 
+    a chart has been applied.
+  </Property>
+
+  <Property name="health_check" type="#health_check" required="optional" value=""> 
+    Health check to run after installing the chart.
+  </Property>
+</Properties>
+
+
+## helm_repository
+
+A `helm_repository` stanza defines the details for a remote helm 
+repository.
+
+<Properties>
+  <Property name="name" type="string" required="true" value=""> 
+    The name of the repository.
+  </Property>
+  <Property name="url" type="string" required="true" value=""> 
+    The repository URL.
+  </Property>
+</Properties>
 
-  <Property name="cluster" type="string" required="true" value="" readonly> 
-    Text
+## health_check
+
+A health_check stanza allows the definition of a health check which must 
+pass before the resource is marked as successfully created.
+
+```hcl
+health_check {
+  timeout = "60s"
+  pods = [
+    "component=server,app=consul", 
+    "component=client,app=consul"
+  ]
+}
+```
+
+<Properties>
+  <Property name="timeout" type="duration" required="true" value="">
+    The maximum duration to wait before marking the health check as failed. 
+    Expressed as a Go duration, e.g. `1s` = 1 second, `100ms` = 100 milliseconds.
   </Property>
+
+  <Property name="pods" type="[]string" required="true" value="">
+    An array of kubernetes selector syntax. The healthcheck ensures that all
+    containers defined by the selector are running before passing the healthcheck.
+  </Property>
+
 </Properties>
 
 <MetaProperties/>
@@ -34,7 +139,7 @@ https://shipyard.run/docs/resources/helm
 
 ```hcl
 resource "helm" "consul" {
-  cluster = resource.k8s_cluster.k3s.id
+  cluster = resource.k8s_cluster.k3s
 
   repository {
     name = "hashicorp"
@@ -62,7 +167,7 @@ resource "helm" "consul" {
 
 ```hcl
 resource "helm" "vault" {
-  cluster = resource.k8s_cluster.k3s.id
+  cluster = resource.k8s_cluster.k3s
   chart = "github.com/hashicorp/vault-helm"
 
   values_string = {
@@ -75,7 +180,7 @@ resource "helm" "vault" {
 
 ```hcl
 resource "helm" "vault" {
-  cluster = resource.k8s_cluster.k3s.id
+  cluster = resource.k8s_cluster.k3s
   chart   = "./files/helm/vault"
 
   values_string = {

diff --git a/src/pages/docs/resources/ingress/index.mdx b/src/pages/docs/resources/ingress/index.mdx
@@ -5,13 +5,27 @@ import MetaProperties from "../shared/meta.mdx"
 <Intro>
 The `ingress` resource allows you to expose services in Kubernetes and Nomad
 tasks to the local machine.
+
+It also allows you to expose applications that are running to the local machine
+to a Kubernetes or Nomad cluster.
 </Intro >
 
 ## Properties
 
 <Properties>
   <Property name="port" type="int" required="true" value="">
-    The local port to expose the service on.
+    If the application to be exposed exists on the target then this is the
+    port that will be opened on the local machine that will direct traffic
+    to the remote service.
+
+    If the application exists on the local machine then this is the port
+    where the application is running.
+  </Property>
+
+  <Property name="expose_local" type="boolean" required="false" value="false">
+    If set to true a service running on the local machine will be exposed to 
+    the target cluster. If false then a service running on the target cluster
+    will be exposed to the local machine.
   </Property>
 
   <Property name="target" type="#traffic_target" required="true" value="">
@@ -22,11 +36,18 @@ tasks to the local machine.
     The unique identifier for the created ingress.
   </Property>
 
-  <Property name="address" type="string" required="false" value="" readonly>
-    The full address where the ingress can be reached from the local network.
+  <Property name="local_address" type="string" required="false" value="" readonly>
+    The full address where the exposed application can be reached from the 
+    local network.
 
     Generally this is the local ip address of the machine running Jumppad and the
-    port where the service is exposed.
+    port where the application is exposed.
+  </Property>
+
+  <Property name="remote_address" type="string" required="false" value="" readonly>
+    The address of the exposed service as it would be rechable from the target
+    cluster. This is generally a kubernetes service reference and port or for Nomad
+    a rechable IP address and port.
   </Property>
 </Properties>
 
@@ -35,8 +56,27 @@ tasks to the local machine.
 ## traffic_target
 
 <Properties>
-  <Property name="id" type="string" required="true" value="">
-    The id of the `nomad_cluster` or `kubernetes_cluster` resource.
+  <Property name="resource" type="remote cluster" required="true" value="">
+    A reference to the `nomad_cluster` or `kubernetes_cluster` resource.
+
+    ```hcl
+    resource "k8s_cluster" "dev" {
+    }
+
+    resource "ingress" "consul_http" {
+      port = 18500
+
+      target {
+        resource = resource.k8s_cluster.dev
+        port     = 8500
+
+        config = {
+          service   = "consul-consul-server"
+          namespace = "default"
+        }
+      }
+    }
+    ```
   </Property>
 
   <Property name="port" type="int" required="true" value="">
@@ -46,7 +86,7 @@ tasks to the local machine.
   </Property>
 
   <Property name="named_port" type="string" required="true" value="">
-    The streing reference for the target service port.
+    The string reference for the target service port.
 
     Either `port` or `named_port` must be specified.
   </Property>
@@ -74,7 +114,7 @@ tasks to the local machine.
 
 ## Examples
 
-### Nomad Ingress
+### Nomad Remote Service
 
 Exposes the the `http` port for the task `fake_service` in the group `fake_service` 
 in the job `example_1` locally on port `19090`
@@ -84,7 +124,7 @@ resource "ingress" "fake_service_1" {
   port = 19090
 
   target {
-    id         = resource.nomad_cluster.dev.id
+    resource   = resource.nomad_cluster.dev
     named_port = "http"
 
     config = {
@@ -96,7 +136,7 @@ resource "ingress" "fake_service_1" {
 }
 ```
 
-### Kubernets Ingress
+### Kubernets Remote Service
 
 Exposes the Kubernets port `9090` for the Kubernetes service `fake-service` 
 in the `default` namespace locally on port `19090`.
@@ -106,7 +146,7 @@ resource "ingress" "fake_service_1" {
   port = 19090
 
   target {
-    id   = resource.k8s_cluster.k3s.id
+    resource = resource.k8s_cluster.k3s.id
     port = 9090
 
     config = {
@@ -115,4 +155,36 @@ resource "ingress" "fake_service_1" {
     }
   }
 }
+```
+
+### Kubernets Local Service
+
+Exposes the local port `9090` used by the app container, as a the Kubernetes service `fake-service` 
+in the `jumppad` namespace on port `80`.
+
+```hcl
+resource "container" "app" {
+  image {
+    name = variable.image
+  }
+
+  port {
+    local  = 9090
+    remote = 9090
+    host = 9090 
+  }
+}
+
+resource "ingress" "fake_service_1" {
+  port = 9090
+
+  target {
+    resource = resource.k8s_cluster.k3s
+    port = 80
+
+    config = {
+      service   = "fake-service"
+    }
+  }
+}
 ```
diff --git a/src/pages/docs/resources/k8s/kubernetes_cluster.mdx b/src/pages/docs/resources/k8s/kubernetes_cluster.mdx
@@ -55,6 +55,9 @@ clusters running in Docker containers using K3s.
     This image is added to the Nomad clients docker cache enabling jobs to use
     images that may not be in the local registry.
 
+    Jumppad tracks changes to copied images, should the image change running
+    `jumppad up` would push any changes to the cluster automatically.
+
     ```hcl
     copy_image {
       name = "mylocalimage:versoin"