> For the complete documentation index, see [llms.txt](https://docs.cloudscript.ai/cloudscript/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudscript.ai/cloudscript/cloudscript-cli/advanced-topics-and-troubleshooting.md).

# Advanced Topics and Troubleshooting

### Network Configuration

#### Automatic Network Setup

The CLI can automatically handle the list of things below in case of SSH permission issues:

1. VPC creation/configuration
2. Subnet management
3. Internet gateway attachment
4. Route table configuration
5. Security group rules
6. Firewall settings

#### SSH Access Management

The CLI manages SSH access by:

1. Creating SSH key pairs
2. Configuring security groups
3. Setting up instance metadata
4. Managing key permissions
5. Handling different OS users

### Limitations and Known Issues

#### Current Limitations

1. Single region deployment per configuration
2. No direct support for:
   * Multi-cloud deployments
   * Azure resources
   * Custom VPC peering
   * Advanced networking features
3. No support for stateful workloads
4. Relatively static Ansible integration

#### Resource Management

* Resources must be defined in `.cloud` file
* Manual changes to resources may cause sync issues
* Key pairs are managed automatically
* Some resource types require manual cleanup

### Best Practices

#### Project Organization

1. Use different names for all resources within each `.cloud`file
2. Separate configurations by deployment zone
3. Document file references
4. Maintain backup copies

### Troubleshooting

#### Common Issues

**Convert Command Fails**

```plaintext
Error: No .cloud file found in the specified path
```

**Solution**: Ensure you're providing the correct path and the `.cloud` file exists.

**Network Access Issues**

```plaintext
Error: Could not establish SSH connection to instance
```

**Solution**:

1. Check security group rules
2. Verify instance has public IP
3. Confirm SSH key permissions
4. Check OS user configuration

**Permission Issues**

```plaintext
Error: AWS API call failed: AccessDenied
```

**Solution**:

1. Verify AWS credentials
2. Check IAM permissions
3. Ensure role/policy attachments

### Error Handling

#### Error Categories

1. **Infrastructure Errors**
   * Resource creation failures
   * Network configuration issues
   * Permission problems
2. **Container Errors**
   * Image pull failures
   * Configuration issues
   * Resource constraints
3. **Configuration Errors**
   * Ansible playbook failures
   * Package installation issues
   * Service configuration problems

#### Error Resolution Steps

1. Check the logs
2. Verify credentials
3. Validate configurations
4. Check resource availability
5. Review network settings

### Future Enhancements

1. Multi-cloud support
2. Azure integration
3. Advanced networking features
4. Enhanced state management
5. Error Mapping