From d3c77524b7cd8eddec96244e6a946c52985d4c73 Mon Sep 17 00:00:00 2001 From: Travis Cline Date: Wed, 25 Sep 2024 12:23:11 -0700 Subject: [PATCH] docs: Improve docs (#24) * docs: fix sphinx-compat links * preflight: add some docs * docs: regenerate * preflight: Improve errro handling, cleanup lint issues * preflight: Address other lint issues --- cmd/docs.go | 7 ++- cmd/preflight/brev/brev.go | 8 ++- cmd/preflight/check/check.go | 97 +++++++++++++----------------- cmd/preflight/debug/debug_start.go | 18 ++++-- docs/nvcf.md | 7 ++- docs/nvcf_auth.md | 2 +- docs/nvcf_auth_configure-docker.md | 2 +- docs/nvcf_auth_login.md | 2 +- docs/nvcf_auth_logout.md | 2 +- docs/nvcf_auth_org-id.md | 2 +- docs/nvcf_auth_orgs.md | 2 +- docs/nvcf_auth_status.md | 2 +- docs/nvcf_auth_whoami.md | 2 +- docs/nvcf_function.md | 2 +- docs/nvcf_function_create.md | 16 ++++- docs/nvcf_function_delete.md | 2 +- docs/nvcf_function_deploy.md | 2 +- docs/nvcf_function_get.md | 19 +++--- docs/nvcf_function_list.md | 2 +- docs/nvcf_function_stop.md | 2 +- docs/nvcf_function_update.md | 2 +- docs/nvcf_function_watch.md | 2 +- docs/nvcf_gpu.md | 2 +- docs/nvcf_gpu_list.md | 2 +- docs/nvcf_preflight.md | 2 +- docs/nvcf_preflight_check.md | 11 +++- 26 files changed, 128 insertions(+), 91 deletions(-) diff --git a/cmd/docs.go b/cmd/docs.go index 618a162..cbfd0e3 100644 --- a/cmd/docs.go +++ b/cmd/docs.go @@ -49,7 +49,12 @@ func generateDocs(cmd *cobra.Command, genMarkdown, genReST bool) error { } // Generate reStructuredText documentation if genReST { - if err := doc.GenReSTTree(root, outputDir); err != nil { + emptyStr := func(s string) string { return "" } + linkHandler := func(name, ref string) string { + //sphinx-style refs. + return fmt.Sprintf(":ref:`%s <%s>`", name, ref) + } + if err := doc.GenReSTTreeCustom(root, outputDir, emptyStr, linkHandler); err != nil { return fmt.Errorf("failed to generate reStructuredText documentation: %w", err) } fmt.Println("reStructuredText documentation generated") diff --git a/cmd/preflight/brev/brev.go b/cmd/preflight/brev/brev.go index 95bdf7c..5b0ddf0 100644 --- a/cmd/preflight/brev/brev.go +++ b/cmd/preflight/brev/brev.go @@ -71,7 +71,9 @@ func (c *BrevClient) RunDebuggingScript(instanceName string, image string, image debuggingScript := generateDebuggingScript(image, imageArgs) cmd := exec.Command("brev", "refresh") - cmd.Run() + if err := cmd.Run(); err != nil { + return fmt.Errorf("issue running `brev refresh`: %w", err) + } sshAlias := instanceName sshCmd := []string{ @@ -126,7 +128,7 @@ func runSSHExec(sshAlias string, args []string) error { return fmt.Errorf("error getting stdin pipe: %w", err) } for _, arg := range args { - si.Write([]byte(arg + "\n")) + _, _ = si.Write([]byte(arg + "\n")) } si.Close() @@ -173,7 +175,7 @@ func saveDebugInstance(functionId, instanceName string) error { instances := make(map[string]string) data, err := os.ReadFile(configPath) if err == nil { - json.Unmarshal(data, &instances) + _ = json.Unmarshal(data, &instances) } // Add or update the new instance diff --git a/cmd/preflight/check/check.go b/cmd/preflight/check/check.go index 5607f2a..f2f6586 100644 --- a/cmd/preflight/check/check.go +++ b/cmd/preflight/check/check.go @@ -32,12 +32,21 @@ func CheckCmd() *cobra.Command { Use: "check ", Short: "Run local deployment test for NVCF compatibility", Long: `Run a local deployment test to verify container compatibility with NVCF. + This command deploys the specified Docker image locally, checks its health, -and performs basic connectivity tests to ensure it meets NVCF requirements.`, +and performs basic connectivity tests to ensure it meets NVCF requirements. + +Key features: +- Supports both HTTP and gRPC protocols +- Customizable health check and inference endpoints +- Configurable wait times for container readiness +- Option to force cleanup of existing containers + +Use this command to validate your NVCF function before deployment.`, Args: cobra.ExactArgs(1), - Run: func(cmd *cobra.Command, args []string) { + RunE: func(cmd *cobra.Command, args []string) error { imageName = args[0] - runLocalDeploymentTest() + return runLocalDeploymentTest() }, } cmd.Flags().StringVar(&containerPort, "container-port", "8000", "Port that the server is listening on") @@ -53,85 +62,63 @@ and performs basic connectivity tests to ensure it meets NVCF requirements.`, return cmd } -func runLocalDeploymentTest() { +func runLocalDeploymentTest() error { if protocol == "grpc" && (grpcServiceName == "" || grpcMethodName == "") { - fmt.Println("Error: gRPC service name and method name are required for gRPC protocol") - os.Exit(1) + return fmt.Errorf("gRPC service name and method name are required for gRPC protocol") } - cst, err := containerutil.NewContainerSmokeTest() if err != nil { - fmt.Printf("Error creating ContainerSmokeTest: %v\n", err) - os.Exit(1) + return fmt.Errorf("error creating ContainerSmokeTest: %w", err) } - // Set up signal handling for graceful shutdown sigChan := make(chan os.Signal, 1) signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM) go func() { <-sigChan fmt.Println("\nReceived interrupt signal. Cleaning up...") - cst.Cleanup() - os.Exit(1) + _ = cst.Cleanup() }() - // Force cleanup if requested if forceCleanup { fmt.Println("Forcing cleanup of existing containers...") if err := cst.ForceCleanup(imageName); err != nil { - fmt.Printf("Error during force cleanup: %v\n", err) - os.Exit(1) + return fmt.Errorf("error during force cleanup: %w", err) } } - - defer cst.Cleanup() - - err = cst.LaunchContainer(imageName, containerPort) - if err != nil { - fmt.Printf("Error launching container: %v\n", err) - os.Exit(1) + defer func() { + _ = cst.Cleanup() + }() + if err := cst.LaunchContainer(imageName, containerPort); err != nil { + return fmt.Errorf("error launching container: %w", err) } - + var healthErr error if protocol == "http" { - err = cst.CheckHTTPHealthEndpoint(healthEndpoint, secondsToWaitForHealthy) + healthErr = cst.CheckHTTPHealthEndpoint(healthEndpoint, secondsToWaitForHealthy) } else { - err = cst.CheckGRPCHealthEndpoint(secondsToWaitForHealthy) + healthErr = cst.CheckGRPCHealthEndpoint(secondsToWaitForHealthy) } - - if err != nil { - fmt.Printf("Error checking health endpoint: %v\n", err) - os.Exit(1) + if healthErr != nil { + return fmt.Errorf("error checking health endpoint: %w", healthErr) } - fmt.Println("Health Check succeeded!") - if protocol == "http" { var payload interface{} - err := json.Unmarshal([]byte(httpPayload), &payload) - if err != nil { - fmt.Printf("Error parsing HTTP payload: %v\n", err) - os.Exit(1) + if err := json.Unmarshal([]byte(httpPayload), &payload); err != nil { + return fmt.Errorf("error parsing HTTP payload: %w", err) } - - err = cst.TestHTTPInference(httpInferenceEndpoint, payload) - if err != nil { - fmt.Printf("Error testing HTTP inference: %v\n", err) - fmt.Println("HTTP inference test failed. Please check your application's endpoints and try again.") - os.Exit(1) - fmt.Println("HTTP inference test succeeded!") - } else if protocol == "grpc" { - var inputData map[string]interface{} - err := json.Unmarshal([]byte(grpcInputData), &inputData) - if err != nil { - fmt.Printf("Error parsing gRPC input data: %v\n", err) - os.Exit(1) - } - - err = cst.TestGRPCInference(grpcServiceName, grpcMethodName, inputData, false) - if err != nil { - fmt.Printf("Error testing gRPC inference: %v\n", err) - os.Exit(1) - } + if err := cst.TestHTTPInference(httpInferenceEndpoint, payload); err != nil { + return fmt.Errorf("error testing HTTP inference: %w", err) + } + fmt.Println("HTTP inference test succeeded!") + } else if protocol == "grpc" { + var inputData map[string]interface{} + if err := json.Unmarshal([]byte(grpcInputData), &inputData); err != nil { + return fmt.Errorf("error parsing gRPC input data: %w", err) + } + if err := cst.TestGRPCInference(grpcServiceName, grpcMethodName, inputData, false); err != nil { + return fmt.Errorf("error testing gRPC inference: %w", err) } + fmt.Println("gRPC inference test succeeded!") } + return nil } diff --git a/cmd/preflight/debug/debug_start.go b/cmd/preflight/debug/debug_start.go index 17a45da..abdd42b 100644 --- a/cmd/preflight/debug/debug_start.go +++ b/cmd/preflight/debug/debug_start.go @@ -19,9 +19,17 @@ func debugStartCmd() *cobra.Command { cmd := &cobra.Command{ Use: "start ", Short: "Start a debug environment", - Long: `Create and start a debug environment for an NVCF function`, - Args: cobra.ExactArgs(1), - RunE: runDebugStart, + Long: `Create and start a debug environment for an NVCF function. + +This command sets up a GPU-powered VM using Brev CLI, pulls the function's +container image, and runs it in a debugging session. It allows you to: +- Debug functions with ERROR status +- Specify a particular version for debugging +- Access the debug environment via SSH for hands-on troubleshooting + +Use this command when you need to investigate issues with your NVCF function in a live environment.`, + Args: cobra.ExactArgs(1), + RunE: runDebugStart, } cmd.Flags().String("version-id", "", "The ID of the version") @@ -109,7 +117,9 @@ func runDebugStart(cmd *cobra.Command, args []string) error { instanceName := fmt.Sprintf("nvcf-%s-debug-%s", functionId, randomString) // hit the brev api to create an instance using - brevClient.CreateInstance(functionId, instanceName) + if err := brevClient.CreateInstance(functionId, instanceName); err != nil { + return output.Error(cmd, "Error creating Brev instance", err) + } // run the debugging script on the instance err = brevClient.RunDebuggingScript(instanceName, image, imageArgs) diff --git a/docs/nvcf.md b/docs/nvcf.md index 5846943..d4c4813 100644 --- a/docs/nvcf.md +++ b/docs/nvcf.md @@ -6,6 +6,11 @@ NVIDIA Cloud Functions CLI A command-line interface for managing and interacting with NVIDIA Cloud Functions. +Environment variables: + NVCF_BETA - Set to true to enable beta features + NVCF_SHOW_DOCS_CMD - Set to true to show the docs command + + ``` nvcf [flags] ``` @@ -17,7 +22,7 @@ nvcf [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_auth.md b/docs/nvcf_auth.md index 1f84fd3..dd0e304 100644 --- a/docs/nvcf_auth.md +++ b/docs/nvcf_auth.md @@ -18,7 +18,7 @@ Authenticate with NVIDIA Cloud and configure the CLI to use your API key. --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_auth_configure-docker.md b/docs/nvcf_auth_configure-docker.md index 9a2d238..3407b21 100644 --- a/docs/nvcf_auth_configure-docker.md +++ b/docs/nvcf_auth_configure-docker.md @@ -18,7 +18,7 @@ nvcf auth configure-docker [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_auth_login.md b/docs/nvcf_auth_login.md index 5c4b84c..1d07c32 100644 --- a/docs/nvcf_auth_login.md +++ b/docs/nvcf_auth_login.md @@ -18,7 +18,7 @@ nvcf auth login [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_auth_logout.md b/docs/nvcf_auth_logout.md index 5cd6dcb..74cc612 100644 --- a/docs/nvcf_auth_logout.md +++ b/docs/nvcf_auth_logout.md @@ -18,7 +18,7 @@ nvcf auth logout [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_auth_org-id.md b/docs/nvcf_auth_org-id.md index fe9cd91..858a560 100644 --- a/docs/nvcf_auth_org-id.md +++ b/docs/nvcf_auth_org-id.md @@ -18,7 +18,7 @@ nvcf auth org-id [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_auth_orgs.md b/docs/nvcf_auth_orgs.md index 32e59be..bbc75f7 100644 --- a/docs/nvcf_auth_orgs.md +++ b/docs/nvcf_auth_orgs.md @@ -19,7 +19,7 @@ nvcf auth orgs [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_auth_status.md b/docs/nvcf_auth_status.md index 03edc83..cd815b1 100644 --- a/docs/nvcf_auth_status.md +++ b/docs/nvcf_auth_status.md @@ -18,7 +18,7 @@ nvcf auth status [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_auth_whoami.md b/docs/nvcf_auth_whoami.md index 1484ec8..4fd99b6 100644 --- a/docs/nvcf_auth_whoami.md +++ b/docs/nvcf_auth_whoami.md @@ -18,7 +18,7 @@ nvcf auth whoami [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function.md b/docs/nvcf_function.md index 2ef6dee..d0cceb2 100644 --- a/docs/nvcf_function.md +++ b/docs/nvcf_function.md @@ -21,7 +21,7 @@ on your serverless functions. --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function_create.md b/docs/nvcf_function_create.md index d8cd292..1234fe1 100644 --- a/docs/nvcf_function_create.md +++ b/docs/nvcf_function_create.md @@ -10,6 +10,20 @@ Create a new NVCF Function with the specified parameters. If you specify --from- nvcf function create [flags] ``` +### Examples + +``` +Create a new function: +nvcf function create --name myfunction --inference-url /v1/chat/completions --inference-port 80 --health-uri /health --container-image nvcr.io/nvidia/example-image:latest + +Create and deploy a new function from a file: +nvcf function create --file deploy.yaml --deploy + +Create a new version of an existing function: +nvcf function create --from-version existing-function-id --name newversion --inference-url /v2/chat/completions --inference-port 8080 --health-uri /healthcheck --container-image nvcr.io/nvidia/updated-image:v2 + +``` + ### Options ``` @@ -49,7 +63,7 @@ nvcf function create [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function_delete.md b/docs/nvcf_function_delete.md index 2135506..c8ab43c 100644 --- a/docs/nvcf_function_delete.md +++ b/docs/nvcf_function_delete.md @@ -31,7 +31,7 @@ nvcf function delete fid --version-id vid --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function_deploy.md b/docs/nvcf_function_deploy.md index bf3a747..768605d 100644 --- a/docs/nvcf_function_deploy.md +++ b/docs/nvcf_function_deploy.md @@ -36,7 +36,7 @@ nvcf function deploy fid --version-id vid --gpu A100 --instance-type g5.4xlarge --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function_get.md b/docs/nvcf_function_get.md index e2f1f3c..384c00d 100644 --- a/docs/nvcf_function_get.md +++ b/docs/nvcf_function_get.md @@ -4,24 +4,29 @@ Get details about a single function and its versions ### Synopsis -Get details about a single function and its versions or deployments. If a version-id is not provided and there are multiple versions associated with a function, we will look for all versions and prompt for a version-id. +Get details about a single function and its versions or deployments. The identifier can be a function name, function ID, or version ID. If no identifier is provided, all functions will be listed. ``` -nvcf function get [flags] +nvcf function get [identifier] [flags] ``` ### Examples ``` -nvcf function get fid --version-id vid --include-secrets +nvcf function get myFunction +nvcf function get fid123 +nvcf function get --name myFunction +nvcf function get --function-id fid123 --version-id vid456 ``` ### Options ``` - -h, --help help for get - --include-secrets Include secrets in the response - --version-id string The ID of the version + --function-id string Filter by function ID + -h, --help help for get + --include-secrets Include secrets in the response + --name string Filter by function name + --version-id string Filter by version ID ``` ### Options inherited from parent commands @@ -30,7 +35,7 @@ nvcf function get fid --version-id vid --include-secrets --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function_list.md b/docs/nvcf_function_list.md index b9a8d78..1eeec1f 100644 --- a/docs/nvcf_function_list.md +++ b/docs/nvcf_function_list.md @@ -30,7 +30,7 @@ nvcf function list --visibility authorized --status ACTIVE,DEPLOYING --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function_stop.md b/docs/nvcf_function_stop.md index f09ab23..dd5f5de 100644 --- a/docs/nvcf_function_stop.md +++ b/docs/nvcf_function_stop.md @@ -31,7 +31,7 @@ nvcf function stop fid --version-id vid --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function_update.md b/docs/nvcf_function_update.md index c77f567..a56c500 100644 --- a/docs/nvcf_function_update.md +++ b/docs/nvcf_function_update.md @@ -34,7 +34,7 @@ nvcf function update fid --version-id vid --gpu A100 --instance-type g5.4xlarge --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_function_watch.md b/docs/nvcf_function_watch.md index 7270dd0..1798809 100644 --- a/docs/nvcf_function_watch.md +++ b/docs/nvcf_function_watch.md @@ -24,7 +24,7 @@ nvcf function watch [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_gpu.md b/docs/nvcf_gpu.md index c9c5935..2f9ea38 100644 --- a/docs/nvcf_gpu.md +++ b/docs/nvcf_gpu.md @@ -18,7 +18,7 @@ List available GPUs, cluster groups, and other GPU related information --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_gpu_list.md b/docs/nvcf_gpu_list.md index c398e01..115a8a1 100644 --- a/docs/nvcf_gpu_list.md +++ b/docs/nvcf_gpu_list.md @@ -24,7 +24,7 @@ nvcf gpu list [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_preflight.md b/docs/nvcf_preflight.md index b92f9e7..b0fb765 100644 --- a/docs/nvcf_preflight.md +++ b/docs/nvcf_preflight.md @@ -18,7 +18,7 @@ Run various preflight checks to ensure compatibility with NVIDIA Cloud Functions --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO diff --git a/docs/nvcf_preflight_check.md b/docs/nvcf_preflight_check.md index 61e28d6..31c9f87 100644 --- a/docs/nvcf_preflight_check.md +++ b/docs/nvcf_preflight_check.md @@ -5,9 +5,18 @@ Run local deployment test for NVCF compatibility ### Synopsis Run a local deployment test to verify container compatibility with NVCF. + This command deploys the specified Docker image locally, checks its health, and performs basic connectivity tests to ensure it meets NVCF requirements. +Key features: +- Supports both HTTP and gRPC protocols +- Customizable health check and inference endpoints +- Configurable wait times for container readiness +- Option to force cleanup of existing containers + +Use this command to validate your NVCF function before deployment. + ``` nvcf preflight check [flags] ``` @@ -34,7 +43,7 @@ nvcf preflight check [flags] --json Output results in JSON format --no-color Disable color output -q, --quiet Suppress non-error output - -v, --verbose Enable verbose output + -v, --verbose Enable verbose output and show underlying API calls ``` ### SEE ALSO