[Docs] updates (#2418)

* [Docs] updates added missing CLI reference sections. modified help text, which improves the docs. updated compute class docs. Signed-off-by: Bill Maxwell <[email protected]> * Update golden file to reflect edit help text Signed-off-by: Bill Maxwell <[email protected]> --------- Signed-off-by: Bill Maxwell <[email protected]>
acorn-io · Jan 17, 2024 · 73ab0b0 · 73ab0b0
1 parent 70b569f
commit 73ab0b0
Show file tree

Hide file tree

Showing 7 changed files with 44 additions and 9 deletions.
diff --git a/docs/Acornfile b/docs/Acornfile
@@ -2,15 +2,16 @@ containers: default: {
 	build: {
 		context: "."
 	}
+	memory: 1500Mi
 
 	if args.dev {
-		build: target: "dynamic"
-		ports: publish: "3000/http"
+		build: target:    "dynamic"
+		ports: publish:   "3000/http"
 		dirs: "/usr/src": "./"
 	}
 
 	if !args.dev {
-		build: target: "static"
+		build: target:  "static"
 		ports: publish: "80/http"
 	}
 }
diff --git a/docs/docs/100-reference/01-command-line/acorn.md b/docs/docs/100-reference/01-command-line/acorn.md
@@ -34,7 +34,7 @@ acorn [flags]
 * [acorn credential](acorn_credential.md)	 - Manage registry credentials
 * [acorn dashboard](acorn_dashboard.md)	 - Open the web dashboard for the project
 * [acorn dev](acorn_dev.md)	 - Run an app from an image or Acornfile in dev mode or attach a dev session to a currently running app
-* [acorn edit](acorn_edit.md)	 - Edits an acorn or secret interactively
+* [acorn edit](acorn_edit.md)	 - Edits an acorn or secret interactively. The things you can change with acorn edit are the same things you can set via the CLI when running acorn run.
 * [acorn events](acorn_events.md)	 - List events about Acorn resources
 * [acorn exec](acorn_exec.md)	 - Run a command in a container
 * [acorn fmt](acorn_fmt.md)	 - Format an Acornfile

diff --git a/docs/docs/100-reference/01-command-line/acorn_edit.md b/docs/docs/100-reference/01-command-line/acorn_edit.md
@@ -3,7 +3,7 @@ title: "acorn edit"
 ---
 ## acorn edit
 
-Edits an acorn or secret interactively
+Edits an acorn or secret interactively. The things you can change with acorn edit are the same things you can set via the CLI when running acorn run.
 
 ```
 acorn edit ACORN_NAME|SECRET_NAME [flags]

diff --git a/docs/docs/40-admin/03-computeclasses.md b/docs/docs/40-admin/03-computeclasses.md
@@ -21,11 +21,11 @@ memory:
   min: 1Gi
   max: 2Gi
   default: 1Gi # This default overrides the install-wide memory default
-  requestScaler: .5 # A percentage of memory to request in relation to the limit, will not go below a configured min value
+  requestScaler: .5 # Scales the requested memory by this amount to allow over provisioning of memory. Containers will not be able to use more memory then the user requested amount.
   values: # Specific values that are only allowed to be used. Default must be included in these values and max/min cannot be set.
   - 1.5Gi
 cpuScaler: 1 # This is used as a ratio of how many VCPUs to schedule per Gibibyte of memory. In this case it is 1 to 1.
-resources: # The same resources fields for Pods: memory and CPU values will be overwritten by memory and cpuScaler fields
+resources: # memory and CPU can not be specified in the resources field. 
   limits:
     gpu-vendor.example/example-limit: 1
   requests:
@@ -56,3 +56,23 @@ If `memory.min`, `memory.max`, `memory.values`, `resources`, `affinity`, and `to
 Cluster Compute Classes are exactly the same as Project Compute Classes except that they are not namespaced. This means that Cluster Workload Classes are available to every app running in your cluster.
 
 Similar to Project Compute Classes, there can be only one default for the entire cluster. However, there can be a default Cluster Compute Class and a default Project Compute Class for any project; the Project Compute Class default will take precedence in this situation. Similarly, if a Cluster Compute Class and a Project Compute Class exist with the same name, then the Project Compute Class will take precedence. These rules are applied when deploying apps and also when using the [`acorn offerings volumeclasses`](100-reference/01-command-line/acorn_offerings_computeclasses.md) command.
+
+## Resource provisioning
+
+Compute classes are the primary way to carve up resources in the cluster. When configuring the computeClasses, you should look at the ammount of RAM you have on a host and determine the ratio of CPU to RAM you want to use.
+
+### Example no over provisioning
+
+If you have a 4vCPU machine with 16GiB of RAM you have a 4:16 ratio of CPU to RAM.
+
+If you want to use 1GiB of RAM per vCPU you would set the CPU scalar to .25.
+
+4 vCPU / 16GiB RAM = .25 vCPU per GiB of RAM
+
+### Example over provisioning
+
+Say you want to over provision the resources by 50% to allow higher utilization of the cluster. If you have the same 4vCPU machine with 16GiB of RAM you have a 4:16 ratio of CPU to RAM. You would still set the CPU scalar to .25.
+
+In that configuration you'll be able to run ~16 workloads. Some resources will be unavailable for workloads for system level processes needed to orchestrate the system.
+
+If you would like to be able to run ~32 workloads you would set the resourceScalar field to .5. This value will be used to scale the requested resources by the user.  So if a user requests 1GiB of RAM, the scheduler will only request 512MiB for the workload. The user will only be able to use up to the 1GiB they requested.
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -59,33 +59,46 @@ const sidebars = {
             "reference/command-line/acorn_check",
             "reference/command-line/acorn_container",
             "reference/command-line/acorn_container_kill",
+            "reference/command-line/acorn_copy",
             "reference/command-line/acorn_credential",
             "reference/command-line/acorn_credential_login",
             "reference/command-line/acorn_credential_logout",
+            "reference/command-line/acorn_dashboard",
+            "reference/command-line/acorn_dev",
+            "reference/command-line/acorn_edit",
             "reference/command-line/acorn_events",
             "reference/command-line/acorn_exec",
             "reference/command-line/acorn_image",
+            "reference/command-line/acorn_image_copy",
+            "reference/command-line/acorn_image_details",
             "reference/command-line/acorn_image_rm",
             "reference/command-line/acorn_info",
             "reference/command-line/acorn_install",
+            "reference/command-line/acorn_job",
+            "reference/command-line/acorn_job_restart",
             "reference/command-line/acorn_login",
             "reference/command-line/acorn_logout",
             "reference/command-line/acorn_logs",
             "reference/command-line/acorn_project",
             "reference/command-line/acorn_project_create",
             "reference/command-line/acorn_project_rm",
+            "reference/command-line/acorn_project_update",
             "reference/command-line/acorn_project_use",
             "reference/command-line/acorn_ps",
             "reference/command-line/acorn_pull",
             "reference/command-line/acorn_push",
             "reference/command-line/acorn_offerings",
             "reference/command-line/acorn_offerings_computeclasses",
+            "reference/command-line/acorn_offerings_regions",
             "reference/command-line/acorn_offerings_volumeclasses",
+            "reference/command-line/acorn_port-forward",
             "reference/command-line/acorn_render",
             "reference/command-line/acorn_rm",
             "reference/command-line/acorn_run",
             "reference/command-line/acorn_secret",
             "reference/command-line/acorn_secret_create",
+            "reference/command-line/acorn_secret_edit",
+            "reference/command-line/acorn_secret_update",
             "reference/command-line/acorn_secret_encrypt",
             "reference/command-line/acorn_secret_reveal",
             "reference/command-line/acorn_secret_rm",
@@ -94,6 +107,7 @@ const sidebars = {
             "reference/command-line/acorn_tag",
             "reference/command-line/acorn_uninstall",
             "reference/command-line/acorn_update",
+            "reference/command-line/acorn_version",
             "reference/command-line/acorn_volume",
             "reference/command-line/acorn_volume_rm",
             "reference/command-line/acorn_wait"

diff --git a/pkg/cli/edit.go b/pkg/cli/edit.go
@@ -11,7 +11,7 @@ func NewEdit(c CommandContext) *cobra.Command {
 		Use:               "edit ACORN_NAME|SECRET_NAME",
 		Example:           `acorn edit my-acorn`,
 		SilenceUsage:      true,
-		Short:             "Edits an acorn or secret interactively",
+		Short:             "Edits an acorn or secret interactively. The things you can change with acorn edit are the same things you can set via the CLI when running acorn run.",
 		Args:              cobra.ExactArgs(1),
 		ValidArgsFunction: newCompletion(c.ClientFactory, appsThenSecretsCompletion).complete,
 	})

diff --git a/pkg/cli/testdata/TestAcorn/acorn_info.golden b/pkg/cli/testdata/TestAcorn/acorn_info.golden
@@ -13,7 +13,7 @@ Available Commands:
   credential   Manage registry credentials
   dashboard    Open the web dashboard for the project
   dev          Run an app from an image or Acornfile in dev mode or attach a dev session to a currently running app
-  edit         Edits an acorn or secret interactively
+  edit         Edits an acorn or secret interactively. The things you can change with acorn edit are the same things you can set via the CLI when running acorn run.
   events       List events about Acorn resources
   exec         Run a command in a container
   fmt          Format an Acornfile