Validate an Application Package

The packaging SDK tool can verify that an existing Great Bear Application Package (GBAP) is well formed, providing a benchmark to gate attempts to publish the GBAP to the Great Bear platform.

Note: The validation command only performs static analysis, it does not perform any checks that require a Kubernetes API server to execute (for example, helm install --dry-run --debug).

Validation Steps

The tool performs the following validation steps.

1. Parse and validate the embedded GBAP gbear/appmetadata.yaml file.

   The tool performs both syntactical and semantical analysis on the appmetadata.yaml file to ensure the contents can be successfully parsed by the GB platform when the GBAP is published. Passing this validation step guarantees that the published GBAP can be successfully rendered in the Great Bear Application Store UI, and that the specified deployment configuration can be parsed successfully during the Great Bear site deployment procedure.

2. Validate and lock Helm dependencies.

   • The Great Bear platform expects a GBAP to have all chart dependencies resolved and extracted within the charts subfolder. This ensures that the GBAP is fully encapsulated and removes the need to pull down Charts from remote repositories during the application deployment procedure at the edge. The resolved dependency tree is also used by the SDK tool to ensure the complete set of Kubernetes resource objects within the GBAP can be rendered successfully into correlating manifests.
   • The tool leverages Helm to resolve all dependencies specified in the root GBAP Helm chart. This includes any dependencies on remote repositories that have been directly entered into the root Chart.yaml outside of the SDK tool’s add --helm=XXX command.
   • All remote Helm Chart repositories hosting declared dependencies must be registered within the Helm client on the local host system.
     • Use the helm registry login command to configure authenticated access to each remote repository.
   • On successful dependency resolution, the GBAP will contain a dependency lock file, capturing the version tree used within the context of the complete GBAP validation procedure.

3. Validate the root GBAP Helm Chart using the Helm linter, by default any detected linter ERROR will cause the GBAP validation to fail. The following optional flags can be used to configure the Helm linter coverage:

   • –helmSubCharts: Instructs the tool to apply the Helm linter to all sub-charts within the GBAP charts folder.
   • –strict: Instructs the tool to fail GBAP validation on any Helm linter WARNING or ERROR.
   • –verbose: Instructs the tool to output INFO level messages returned from the Helm linter.

4. Validate that the GBAP contains helm templates that declare the Kubernetes resource object labels expected by the Great Bear platform.

   • There are a set of recommended Kubernetes resource labels documented within the Kubernetes domain, see:

     • Recommended labels
     • Labels and Annotations

     As these are generally accepted as recommended within Kubernetes, existing tools like the helm linter do not verify or mandate that they exist within Helm charts.

   • The Great Bear platform mandates that a subset of these Kubernetes resource labels are defined within a GBAP (otherwise edge deployment fails). The validation command is configured with the following set of required labels and verifies that they are defined against each resource object declared within the embedded helm templates.

     Key	Description	Example	Type	Use Case
     app.kubernetes.io/instance	A unique name identifying the instance of an application	myapp-abcxzy	string	Used to attribute a deployment status to an app instance.

SDK Validation Command

To validate your GBAP, run the gbear app validate command.

Usage:
  gbear application validate PATH [flags]
  gbear app validate PATH [flags]

Flags:
      --helmSubCharts   Validate Helm Sub Charts
  -h, --help   help for validate
      --strict          Validate fails on warnings
      --verbose         Verbose output

The command takes an optional PATH (defaults to current working directory) as a destination to create a GBAP file system tree. If the command detects any syntax and/or semantic states that will cause subsequent GBAP publish or deployment failures, it emits ERROR messages. If it encounters issues that break with convention or recommendation, it emits WARNING messages.

To capture validation failures within a CICD job state, the tool returns an indicative return code: 0 if the GBAP is valid, otherwise 1.

The in-line validation error messages seek to provide sufficient insight to resolve the related error. Additional help for specific validation errors can be found in the Troubleshooting section of this user guide.

Example 1 - Validate a GBAP in the current working directory:

cd /pathTo/myGBAP
gbear app validate

Example 2 - Validate a GBAP in the specified path:

gbear app validate /pathTo/myGBAP

Expected output for a valid GBAP:

Validating Package: /pathTo/myGBAP
- Validating Application Metadata...
- Validating Chart Dependencies...
***
- Performing Chart Lint...
- Validating Kubernetes Resource Labels...
Validation Complete:
Application Metadata: Passed (Errors: 0, Warnings: 0)
Chart Dependencies: Passed (Errors: 0, Warnings: 0)
Chart Lint: Passed (Errors: 0, Warnings: 0)
Kubernetes Resource Labels: Passed (Errors: 0, Warnings: 0)

Resulting GBAP tree:

/pathTo/myGBAP
├── Chart.yaml     
|── charts
|   └── myAppChart 
|   |    ├── templates
│   |    |    ├── _helpers.tpl
│   |    |    ├── deployment.yaml
│   |    |    ├── service.yaml
|   |    └── values.yaml
├── gbear
│   └── appmetadata.yaml
|── Chart.lock    # Captured chart dependency version tree of the validated GBAP