scout

README

CloudZero Scout Package

The CloudZero Scout package provides automatic cloud environment detection for AWS deployments. It identifies the current cloud provider and retrieves essential information like account ID and region.

Purpose

Scout is designed to reduce the need for manual cloud environment configuration in CloudZero Agent deployments. It automatically detects whether the application is running on AWS and retrieves the necessary metadata for cost allocation and monitoring.

Supported Cloud Providers

• Amazon Web Services (AWS) - Retrieves Account ID and Region via Instance Metadata Service (IMDS)

Key Features

• Automatic Detection - No configuration required, detects cloud provider automatically
• Context-Aware - Respects timeouts and cancellation via Go context
• Testable - Provides mock interfaces for unit testing

Integration

Scout is integrated into CloudZero Agent configuration packages to enable automatic environment detection when configuration values are empty.

Documentation

Overview

Package scout provides cloud environment detection and metadata retrieval capabilities for cloud environments.

Example (Basic)

Example_basic demonstrates basic usage of Scout for automatic cloud environment detection. This example uses a mock scout to provide deterministic output.

package main

import (
	"context"
	"fmt"
	"time"

	"go.uber.org/mock/gomock"

	"github.com/cloudzero/cloudzero-agent/app/utils/scout/types"
	"github.com/cloudzero/cloudzero-agent/app/utils/scout/types/mocks"
)

func main() {
	// Create gomock controller
	ctrl := gomock.NewController(nil) // In real tests, pass testing.T
	defer ctrl.Finish()

	// Create mock environment info for deterministic output
	mockInfo := &types.EnvironmentInfo{
		CloudProvider: types.CloudProviderAWS,
		Region:        "us-east-1",
		AccountID:     "123456789012",
	}

	// Create mock scout with expectations
	mockScout := mocks.NewMockScout(ctrl)
	mockScout.EXPECT().
		EnvironmentInfo(gomock.Any()).
		Return(mockInfo, nil)

	// Use mock scout directly (for deterministic examples)
	s := mockScout

	// Set timeout for metadata retrieval
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	// Get environment information
	info, err := s.EnvironmentInfo(ctx)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}

	fmt.Printf("Cloud Provider: %s\n", info.CloudProvider)
	fmt.Printf("Region: %s\n", info.Region)
	fmt.Printf("Account ID: %s\n", info.AccountID)

}

Output:

Cloud Provider: aws
Region: us-east-1
Account ID: 123456789012

Index

• func DetectConfiguration(ctx context.Context, logger *zerolog.Logger, scout types.Scout, region *string, ...) error
• func NewScout() types.Scout

Examples

• Package (Basic)

Functions

func DetectConfiguration

func DetectConfiguration(ctx context.Context, logger *zerolog.Logger, scout types.Scout, region *string, accountID *string, clusterName *string) error

DetectConfiguration provides an easy way to automatically detect cloud provider information from configuration variables which may or may not already contain values.

It is designed for use when loading configuration. If any fields are empty, an auto scout (see the auto subpackage) will be used to attempt to detect the correct values. If the fields are not empty, they will be treated as overrides and left intact, but a warning will be logged if they don't match the detected values.

If any of the fields are unable to be auto-detected AND are required (empty), an error will be returned. If all required fields are already provided, detection failures will only result in warning logs.

If all parameters are nil, no detection will be performed. If logger is nil, no warning logs will be emitted.

func NewScout

func NewScout() types.Scout

NewScout creates a new Scout implementation with auto-detection capabilities.