validate

Nexlayer Validate Command

The validate command provides functionality to validate Nexlayer Deployment YAML configuration files against the schema. It helps users identify and fix issues in their configuration before deployment.

Overview

The validate command:

1. Checks configuration files against the Nexlayer Deployment YAML schema
2. Provides detailed feedback on validation errors through an interactive TUI
3. Offers automatic fixing of common issues with a user-friendly confirmation prompt
4. Detects and converts Kubernetes and Docker Compose format YAML files
5. Validates image references and registry credentials

Usage

# Validate the default nexlayer.yaml in current directory
nexlayer validate

# Validate a specific file
nexlayer validate deployment.yaml

# Validate with detailed output
nexlayer validate --verbose

# Validate with automatic fixes
nexlayer validate --fix

Integration with Deploy Command

The validate command is fully integrated with the deploy command, providing a seamless deployment experience:

1. Automatic Validation: The deploy command automatically runs validation before deployment
2. Auto-Fix Option: Use nexlayer deploy --auto-fix to automatically fix validation issues
3. Dry-Run Mode: Use nexlayer deploy --dry-run to validate and verify Docker images without actual deployment
4. Image Verification: The deploy command verifies Docker images using the same validation rules

Example workflow:

# Validate and verify without deploying
nexlayer deploy --dry-run

# Deploy with automatic fixes
nexlayer deploy --auto-fix

Interactive Validation Flow

The validate command now provides a fully interactive experience:

1. TUI Error Display: When validation errors are found, a Terminal User Interface (TUI) displays:

   • Error header with format detection
   • Specific validation errors with field names and descriptions
   • Required format guidelines
   • Common mistakes to avoid
   • Tailored recommendations based on error type
   • Example YAML structure

2. Fix Confirmation: After reviewing errors, you're prompted to fix issues:

   Would you like to automatically fix these issues? (y/n) >
   

3. Summary of Changes: If you choose to fix the issues, the command:

   • Applies intelligent fixes based on error types
   • Shows a list of changes made
   • Confirms the configuration is now valid

4. Manual Editing: If you choose not to auto-fix, you can manually edit your YAML and run validate again.

Format Detection

The validate command can automatically detect and provide conversion recommendations for:

1. Kubernetes YAML Format:

   • Identifies fields like apiVersion, kind, metadata, etc.
   • Provides specific recommendations for converting to Nexlayer format
   • Can automatically convert Kubernetes YAML to Nexlayer format

2. Docker Compose Format:

   • Identifies fields like version, services, networks, etc.
   • Provides targeted recommendations for converting to Nexlayer format
   • Can automatically convert Docker Compose services to Nexlayer pods

Image Validation

The validate command now checks container images for:

1. Public Image Support:

   • Validates that images are from public registries or properly formatted private registries
   • Prevents deployment failures due to unsupported image references

2. Private Registry Validation:

   • Requires the <% REGISTRY %> placeholder for private images
   • Validates that registryLogin is properly configured when using private images
   • Ensures registry credentials are present when needed

Schema Overview

The Nexlayer Deployment YAML schema defines a specific structure for configuring applications on the Nexlayer platform. It is not Kubernetes or Docker Compose YAML—it is a Nexlayer-specific format.

Key Concepts

• Application: The root container for all deployment configurations
• Pods: Individual containers within the application (each pod is a single container)
• Service Name: The name of a service, which is typically the same as the pod name and is used for internal networking (<pod-name>.pod)
• Special Syntax:
  • <pod-name>.pod for referencing other pods
  • <% URL %> for referencing the application's base URL
  • <% REGISTRY %> for referencing private registry images

Required Naming Structure

Validation Rules

The schema enforces the following rules:

• Application name must be unique across Nexlayer
• Pod names must be unique within the application
• Each pod must have a name, image, and at least one servicePorts entry
• path must start with / for web routing
• mountPath must start with / for filesystem paths
• Environment variable names must be valid
• Volume sizes must be specified as a placeholder (e.g., size: "") since they are injected by Nexlayer
• Labels cannot be specified as they are managed by the platform
• servicePorts must be a list of integers (e.g., - 80, - 3000), with no additional fields

Prohibited Fields

The following fields are managed by Nexlayer and are prohibited in user-defined YAML:

• resources: CPU and memory are handled automatically
• labels: Managed by the platform
• network: Managed internally by Nexlayer
• volumes_from: Use volumes instead
• replicas: Kubernetes-specific
• build: Docker Compose-specific
• depends_on: Docker Compose-specific
• entrypoint: Use the image's default entrypoint unless explicitly translated from Docker Compose
• command: Use the image's default command unless explicitly translated from Docker Compose

IMPORTANT NOTE ON "resources":

- DO NOT include "resources" in your own Nexlayer Deployment YAML files. Nexlayer automatically manages CPU & memory, so this field is prohibited.

- If you view the final (post-deployment) YAML, you may see a "resources" block injected by Nexlayer reflecting actual runtime settings.

- Seeing "resources" in the final environment's config is normal and does NOT indicate a user error, as long as you didn't specify it yourself in your YAML.

Common Mistakes to Avoid

1. ❌ Forgetting the application: block at the start ✅ Always begin your YAML with application:

2. ❌ Using the same pod name twice ✅ Each pod name must be unique

3. ❌ Mixing up path and mountPath ✅ path is for URLs (like /api), mountPath is for volumes (like /data)

4. ❌ Forgetting servicePorts ✅ Each pod needs servicePorts to be accessible

5. ❌ Incorrect pod references ✅ Use <pod-name>.pod to connect services (not IP addresses)

6. ❌ Trying to use Kubernetes or Docker Compose syntax ✅ Nexlayer has its own unique YAML schema

7. ❌ Adding resources.limits manually ✅ Nexlayer automatically configures CPU & Memory for each service

8. ❌ Using local Docker images ✅ Use public images or private registry images with the <% REGISTRY %> placeholder

Examples

Valid Configuration

application:
  name: "my-app"
  pods:
    - name: "web"
      image: "nginx:latest"
      path: "/api"
      servicePorts:
        - 80
        - 443
    - name: "db"
      image: "postgres:latest"
      servicePorts:
        - 5432
      volumes:
        - name: "data"
          mountPath: "/var/lib/postgresql/data"
          size: "1Gi"

Invalid Configuration

application:
  name: "my-app"
  pods:
    - name: "web"
      image: "nginx:latest"
      servicePorts:
        - name: "http"    # Error: servicePorts must be integers only
          port: 80        # Error: Use simple integer format
      resources:          # Error: resources are managed by Nexlayer
        limits:
          cpu: "100m"

Using Private Registry Images

application:
  name: "my-app"
  registryLogin:
    registry: "ghcr.io"
    username: "my-username"
    personalAccessToken: "my-access-token"
  pods:
    - name: "backend"
      image: "<% REGISTRY %>/my-backend-service:latest"
      servicePorts:
        - 3000

Automatic Fixes

The validation command can automatically fix common issues:

• Adding leading slashes to paths
• Converting HTTP URLs to HTTPS
• Fixing volume mount paths
• Correcting path prefixes
• Converting Kubernetes YAML to Nexlayer format
• Converting Docker Compose services to Nexlayer pods
• Replacing local images with public registry images

Related Commands

• deploy: Deploy an application using a validated configuration
• init: Initialize a new Nexlayer project with a template configuration