Skip to content

Commit

Permalink
Added mini variant (#21)
Browse files Browse the repository at this point in the history
* Added mini variant
* AiO requires is_compute=true
* Documentation for the mini variant
* remove unneeded config file
  • Loading branch information
rschmied authored Nov 29, 2024
1 parent 83dfcb2 commit eee45ce
Show file tree
Hide file tree
Showing 7 changed files with 213 additions and 5 deletions.
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
# README

Version 0.3.0, June 4 2024
Version 0.3.1, November 29 2024

With CML 2.7, you can run CML instances on Azure and AWS. We have tested CML deployments using this tool chain in both clouds. **The use of this tool is considered BETA**. The tool has certain requirements and prerequisites which are described in this README and in the [documentation](documentation) directory.

*It is very likely that this tool chain can not be used "as-is"*. It should be forked and adapted to specific customer requirements and environments.

> [!IMPORTANT]
>
> **Version 2.7 vs 2.8**
>
> CML2 version 2.8 has been released in November 2024. As CML 2.8 uses Ubuntu 24.04 as the base operating system, cloud-cml needs to accommodate for that during image selection when bringing up the VM on the hosting service (AWS, Azure, ...). This means that going forward, cloud-cml will support 2.8 and not 2.7 anymore. This release will be the last that does support CML 2.7!
>
> **Support:**
>
> - For customers with a valid service contract, CML cloud deployments are supported by TAC within the outlined constraints. Beyond this, support is done with best effort as cloud environments, requirements and policy can differ to a great extent.
Expand Down
17 changes: 14 additions & 3 deletions config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,25 @@ aws:
flavor: m5zn.metal
flavor_compute: m5zn.metal
profile: permission-profile-goes-here
# when specifying a VPC ID below then this prefix must exist on that VPC!
#
# The following two attributes are used in the aws-mini variant. They specify
# the subnet and the security group ID the CML VM should use. The are NOT
# used when using the regular AWS deployment option (non-mini).
subnet_id: ""
sg_id: ""
#
# The followin values are used by the regular AWS deployment option.
# When specifying a VPC ID below then this prefix must exist on that VPC!
public_vpc_ipv4_cidr: 10.0.0.0/16
enable_ebs_encryption: false
# leave empty to create a custom VPC / Internet gateway, or provide the IDs
#
# Leave empty to create a custom VPC / Internet gateway, or provide the IDs
# of the VPC / gateway to use, they must exist and properly associated.
# also: an IPv6 CIDR prefix must be associated with the specified VPC
vpc_id: ""
gw_id: ""
#
# Use spot instances, when available for the VMs forming the cluster
spot_instances:
use_spot_for_controller: false
use_spot_for_computes: false
Expand Down Expand Up @@ -118,7 +129,7 @@ app:
# **No longer used, see the secret manager section above**
#user: admin
#pass: your-secret-password
software: cml2_2.7.0-4_amd64-20.pkg
software: cml2_2.7.2-26_amd64-29.pkg
# The list must have at least ONE element, this is what the dummy is for in
# case 00- and 01- are commented out!
customize:
Expand Down
52 changes: 51 additions & 1 deletion documentation/AWS.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,12 @@
# AWS

Version 0.3.0, May 24 2023
Version 0.3.1, November 2024

This document contains specific configuration steps to deploy a CML instance in AWS. Some sections from the top level document are repeated here with additional detail regarding AWS.

> [!IMPORTANT]
> The repository includes an alternative deployment method for AWS (aws-mini) which does not create any network resources. It therefore relies on these resources to be available at the time of deploying CML. See the "Mini vs regular deployments" section below!
## General requirements

The tooling uses Terraform to deploy CML instances on AWS. It's therefore required to have a functional Terraform installation on the computer where this tool chain should be used.
Expand All @@ -27,6 +30,52 @@ Some of the steps and procedures outlined below are preparation steps and only n

![flowchart](../images/flowchart.png)

### Mini vs regular deployments

As mentioned at the top, there's an `aws-mini` deployment option as an alternative to the "regular" deployment option. The differences are:

| What | regular flavor | mini flavor |
| ------------------------------------------------------- | -------------- | ----------- |
| Allow CML cluster | yes | no |
| Create VPC | optional | no |
| Create Subnet, IGW, NAT GW, Route table, security group | yes | no |
| Create elastic IP | yes | optional* |
| Create VM network interface | yes | yes |

The mini flavor is useful in case the AWS networking infrastructure is already in place and can not or should not be modified, cloud-cml should simply create a CML instance that uses the existing networking infrastructure by providing the subnet ID and the security group ID that should be used to attach the CML VM to.

*If no Elastic IP should be used and the server should use a private IP from the configured subnet instead then this is configurable in the .tf file. See the comment for the `resource "aws_eip" "server_eip"` inside of `main.tf` for the mini variant.

#### How to enable the mini variant

Edit the `modules/deploy/aws-on.t-f` file and edit the following section:

```hcl
module "aws" {
# source = "./aws-mini"
source = "./aws"
count = var.cfg.target == "aws" ? 1 : 0
options = local.options
}
```

So that it reads:

```hcl
module "aws" {
source = "./aws-mini"
# source = "./aws"
count = var.cfg.target == "aws" ? 1 : 0
options = local.options
}
```

and run the `prepare.sh` script (only when AWS hasn't been selected before, it is selected by default when cloning the repository).

#### Configure the mini variant

Ensure that `aws.subnet_id` and `aws.sg_id`  have valid values and that those resources exist on AWS.

### Terraform installation

Terraform can be downloaded for free from [here](https://developer.hashicorp.com/terraform/downloads). This site has also instructions how to install it on various supported platforms.
Expand Down Expand Up @@ -526,6 +575,7 @@ ssh -p1122 sysadmin@IP_ADDRESS_OF_CONTROLLER /provision/del.sh
```

This requires all labs to be stopped (no running VMs allowed) prior to removing the license. It will only work as long as the provisioned usernames and passwords have not changed between deployment and destruction of the instance.

## VPC support

With 0.3.0, the tooling always adds a custom VPC and doesn't use the default VPC anymore. Additional variables have been added to the configuration file `config.yml` to support this.
Expand Down
117 changes: 117 additions & 0 deletions modules/deploy/aws-mini/main.tf
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
#
# This file is part of Cisco Modeling Labs
# Copyright (c) 2019-2024, Cisco Systems, Inc.
# All rights reserved.
#

locals {
# Late binding required as the token is only known within the module.
# (Azure specific)
vars = templatefile("${path.module}/../data/vars.sh", {
cfg = merge(
var.options.cfg,
# Need to have this as it's referenced in the template (Azure specific)
{ sas_token = "undefined" }
)
}
)

cml_config_controller = templatefile("${path.module}/../data/virl2-base-config.yml", {
hostname = var.options.cfg.common.controller_hostname,
is_controller = true
is_compute = true
cfg = merge(
var.options.cfg,
# Need to have this as it's referenced in the template (Azure specific)
{ sas_token = "undefined" }
)
}
)

# Ensure there's no tabs in the template file! Also ensure that the list of
# reference platforms has no single quotes in the file names or keys (should
# be reasonable, but you never know...)
cloud_config = templatefile("${path.module}/../data/cloud-config.txt", {
vars = local.vars
cml_config = local.cml_config_controller
cfg = var.options.cfg
cml = var.options.cml
common = var.options.common
copyfile = var.options.copyfile
del = var.options.del
interface_fix = var.options.interface_fix
extras = var.options.extras
hostname = var.options.cfg.common.controller_hostname
path = path.module
})
}

data "aws_subnet" "selected_subnet" {
id = var.options.cfg.aws.subnet_id
}

data "aws_security_group" "selected_security_group" {
id = var.options.cfg.aws.sg_id
}

resource "aws_network_interface" "pub_int_cml" {
subnet_id = data.aws_subnet.selected_subnet.id
security_groups = [data.aws_security_group.selected_security_group.id]
}

# If no EIP is needed/wanted, then
# - change public_ip to private_ip in output.tf
# - delete the resource block if no EIP is wanted/needed
# In this case, the machine that runs Terraform / the provisioning must be able
# to reach the private IP address and the security group must permit HTTPS to
# the controller.
resource "aws_eip" "server_eip" {
network_interface = aws_network_interface.pub_int_cml.id
}

resource "aws_instance" "cml_controller" {
instance_type = var.options.cfg.aws.flavor
ami = data.aws_ami.ubuntu.id
iam_instance_profile = var.options.cfg.aws.profile
key_name = var.options.cfg.common.key_name
tags = { Name = "CML-controller-${var.options.rand_id}" }
ebs_optimized = "true"
root_block_device {
volume_size = var.options.cfg.common.disk_size
volume_type = "gp3"
encrypted = var.options.cfg.aws.enable_ebs_encryption
}
network_interface {
network_interface_id = aws_network_interface.pub_int_cml.id
device_index = 0
}
user_data = data.cloudinit_config.cml_controller.rendered
}

data "aws_ami" "ubuntu" {
most_recent = true

filter {
name = "name"
values = ["ubuntu/images/hvm-ssd/ubuntu-focal-20.04-amd64-server-*"]
}

filter {
name = "virtualization-type"
values = ["hvm"]
}

owners = ["099720109477"] # Owner ID of Canonical
}

data "cloudinit_config" "cml_controller" {
gzip = true
base64_encode = true # always true if gzip is true

part {
filename = "cloud-config.yaml"
content_type = "text/cloud-config"
content = local.cloud_config
}
}

14 changes: 14 additions & 0 deletions modules/deploy/aws-mini/output.tf
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
#
# This file is part of Cisco Modeling Labs
# Copyright (c) 2019-2024, Cisco Systems, Inc.
# All rights reserved.
#

output "public_ip" {
# value = aws_instance.cml_controller.private_ip
value = aws_instance.cml_controller.public_ip
}

output "sas_token" {
value = "undefined"
}
11 changes: 11 additions & 0 deletions modules/deploy/aws-mini/variables.tf
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
#
# This file is part of Cisco Modeling Labs
# Copyright (c) 2019-2024, Cisco Systems, Inc.
# All rights reserved.
#

variable "options" {
type = any
description = "module options of the CML deployment as an object"
}

1 change: 1 addition & 0 deletions modules/deploy/aws-on.t-f
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ provider "aws" {
}

module "aws" {
# source = "./aws-mini"
source = "./aws"
count = var.cfg.target == "aws" ? 1 : 0
options = local.options
Expand Down

0 comments on commit eee45ce

Please sign in to comment.