From 1f8b956a5068ec15be6281d1b98bcc6a3b7bf23b Mon Sep 17 00:00:00 2001
From: "create-pr-on-fork-for-pan-dev[bot]"
<135888023+create-pr-on-fork-for-pan-dev[bot]@users.noreply.github.com>
Date: Wed, 19 Jul 2023 21:20:57 +0100
Subject: [PATCH] Sync Terraform module documentation to pan.dev (#442)
---
.../docs/swfw/aws/vmseries/modules/alb.md | 8 +-
.../docs/swfw/aws/vmseries/modules/asg.md | 5 +-
.../docs/swfw/aws/vmseries/modules/gwlb.md | 2 +
.../docs/swfw/aws/vmseries/modules/nlb.md | 3 +-
.../swfw/aws/vmseries/modules/panorama.md | 1 +
.../swfw/aws/vmseries/modules/vmseries.md | 1 +
.../docs/swfw/aws/vmseries/modules/vpc.md | 2 +-
.../47d0ec0b-9080-4af2-b82b-0445e6910975.png | Bin 0 -> 227979 bytes
.../centralized_design.md | 2 +-
.../centralized_design_autoscale.md | 215 +++++++++++++
.../combined_design.md | 2 +-
.../isolated_design.md | 2 +-
.../docs/swfw/azure/vmseries/modules/appgw.md | 8 +-
.../vmseries/modules/application_insights.md | 2 +-
.../swfw/azure/vmseries/modules/bootstrap.md | 7 +-
.../docs/swfw/azure/vmseries/modules/natgw.md | 4 +-
.../swfw/azure/vmseries/modules/panorama.md | 1 -
.../docs/swfw/azure/vmseries/modules/vmss.md | 5 +-
.../common_vmseries.md | 12 +-
.../dedicated_vmseries.md | 12 +-
.../swfw/gcp/vmseries/modules/autoscale.md | 71 +++--
.../swfw/gcp/vmseries/modules/bootstrap.md | 1 +
.../swfw/gcp/vmseries/modules/lb_external.md | 6 +-
.../swfw/gcp/vmseries/modules/lb_internal.md | 7 +-
.../docs/swfw/gcp/vmseries/modules/vpc.md | 2 +-
.../7690846b-2aad-4045-913c-8a5cdb80b16b.png | Bin 0 -> 71886 bytes
.../reference-architectures/vmseries_ha.md | 298 ++++++++++++++++++
27 files changed, 608 insertions(+), 71 deletions(-)
create mode 100644 products/terraform/docs/swfw/aws/vmseries/reference-architectures/47d0ec0b-9080-4af2-b82b-0445e6910975.png
create mode 100644 products/terraform/docs/swfw/aws/vmseries/reference-architectures/centralized_design_autoscale.md
create mode 100644 products/terraform/docs/swfw/gcp/vmseries/reference-architectures/7690846b-2aad-4045-913c-8a5cdb80b16b.png
create mode 100644 products/terraform/docs/swfw/gcp/vmseries/reference-architectures/vmseries_ha.md
diff --git a/products/terraform/docs/swfw/aws/vmseries/modules/alb.md b/products/terraform/docs/swfw/aws/vmseries/modules/alb.md
index 598343315..0b51d218d 100644
--- a/products/terraform/docs/swfw/aws/vmseries/modules/alb.md
+++ b/products/terraform/docs/swfw/aws/vmseries/modules/alb.md
@@ -24,7 +24,7 @@ A Terraform module for deploying an Application Load Balancer in AWS cloud. This
Example usage:
-* The code below is designed to be used with [`vmseries`](../vmseries/README.md), [`vpc`](../vpc/README.md) and [`subnet_set`](../subnet_set/README.md) modules. Check these modules for information on outputs used in this code.
+* The code below is designed to be used with [`vmseries`](../vmseries), [`vpc`](../vpc) and [`subnet_set`](../subnet_set) modules. Check these modules for information on outputs used in this code.
* Firewalls' public facing interfaces are placed in a subnet set called *untrust*.
* There are two rules shown below:
* `defaults` rule shows a minimum setup that uses only default values
@@ -138,10 +138,11 @@ No modules.
| [idle\_timeout](#input\_idle\_timeout) | The time in seconds that the connection to the Load Balancer can be idle. | `number` | `60` | no |
| [lb\_name](#input\_lb\_name) | Name of the Load Balancer to be created. | `string` | n/a | yes |
| [rules](#input\_rules) | An object that contains the listener, listener\_rules, target group, and health check configuration.
It consists of maps of applications with their properties, like in the following example:rules = {
"application\_name" = {
protocol = "communication protocol, since this is an ALB module accepted values are `HTTP` or `HTTPS`"
port = "communication port, defaults to protocol's default port"
certificate\_arn = "(HTTPS ONLY) this is the arn of an existing certificate, this module will not create one for you"
ssl\_policy = "(HTTPS ONLY) name of an ssl policy used by the Load Balancer's listener, defaults to AWS default, for available options see [AWS documentation](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html#describe-ssl-policies)"
health\_check\_protocol = "this can be either `HTTP` or `HTTPS`, defaults to communication protocol"
health\_check\_port = "port used by the target group health check, if omitted, `traffic-port` will be used (which will be the same as communication port)"
health\_check\_healthy\_threshold = "number of consecutive health checks before considering target healthy, defaults to 3"
health\_check\_unhealthy\_threshold = "number of consecutive health checks before considering target unhealthy, defaults to 3"
health\_check\_interval = "time between each health check, between 5 and 300 seconds, defaults to 30s"
health\_check\_timeout = "health check probe timeout, defaults to AWS default value"
health\_check\_matcher = "response codes expected during health check, defaults to `200`"
health\_check\_path = "destination used by the health check request, defaults to `/`"
listener\_rules = "a map of rules for a listener created for this application, see `listener\_rules` block below for more information
}
}The `application_name` key is valid only for letters, numbers and a dash (`-`) - that's an AWS limitation.
There is always one listener created per application. The listener has always a default action that responds with `503`. This should be treated as a `catch-all` rule. For the listener to send traffic to backends a listener rule has to be created. This is controlled via the `listener_rules` map.
A key in this map is the priority of the listener rule. Priority can be between `1` and `50000` (AWS specifics). All properties under a particular key refer to either rule's condition(s) or the target group that should receive traffic if a rule is met.
Rule conditions - at least one but not more than five of: `host_headers`, `http_headers`, `http_request_method`, `path_pattern`, `query_strings` or `source_ip` has to be set. For more information on what conditions can be set for each type refer to [documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb_listener_rule#condition-blocks).
Target group - keep in mind that all target group attachments are always pointing to VMSeries' public interfaces. The difference between target groups for each rule is the protocol and/or port to which the traffic is being directed. And these are the only properties you can configure (`target_protocol`, `protocol_version` and `target_port` respectively).
The `listener_rules` map presents as follows:listener\_rules = {
"rule\_priority" = { # string representation of a rule's priority (number from 1 - 50000)
target\_port = "port on which the target is listening for requests"
target\_protocol = "target protocol, can be `HTTP` or `HTTPS`"
protocol\_version = "one of `HTTP1`, `HTTP/2` or `GRPC`, defaults to `HTTP1`"
round\_robin = "bool, if set to true (default) the `round-robin` load balancing algorithm is used, otherwise a target attachment with least outstanding requests is chosen.
host\_headers = "a list of possible host headers, case insensitive, wildcards (`*`,`?`) are supported"
http\_headers = "a map of key-value pairs, where key is a name of an HTTP header and value is a list of possible values, same rules apply like for `host\_headers`"
http\_request\_method = "a list of possible HTTP request methods, case sensitive (upper case only), strict matching (no wildcards)"
path\_pattern = "a list of path patterns (w/o query strings), case sensitive, wildcards supported"
query\_strings = "a map of key-value pairs, key is a query string key pattern and value is a query string value pattern, case insensitive, wildcards supported, it is possible to match only a value pattern (the key value should be prefixed with `nokey\_`)"
source\_ip = "a list of source IP CDIR notation to match"
}
}
EXAMPLElistener\_rules = {
"1" = {
target\_port = 8080
target\_protocol = "HTTP"
host\_headers = ["public-alb-1050443040.eu-west-1.elb.amazonaws.com"]
http\_headers = {
"X-Forwarded-For" = ["192.168.1.*"]
}
http\_request\_method = ["GET"]
}
"99" = {
host\_headers = ["www.else.org"]
target\_port = 8081
target\_protocol = "HTTP"
path\_pattern = ["/", "/login.php"]
query\_strings = {
"lang" = "us"
"nokey\_1" = "test"
}
source\_ip = ["10.0.0.0/8"]
}
} | `any` | n/a | yes |
-| [security\_groups](#input\_security\_groups) | A list of security group IDs to use with a Load Balancer.
If security groups are created with a [VPC module](../vpc/README.md) you can use output from that module like this:security\_groups = [module.vpc.security\_group\_ids["load\_balancer\_security\_group"]]
For more information on the `load_balancer_security_group` key refer to the [VPC module documentation](../vpc/README.md). | `list(string)` | n/a | yes |
+| [security\_groups](#input\_security\_groups) | A list of security group IDs to use with a Load Balancer.
If security groups are created with a [VPC module](../vpc) you can use output from that module like this:security\_groups = [module.vpc.security\_group\_ids["load\_balancer\_security\_group"]]
For more information on the `load_balancer_security_group` key refer to the [VPC module documentation](../vpc). | `list(string)` | n/a | yes |
| [subnets](#input\_subnets) | Map of subnets used with a Load Balancer. Each key is the availability zone name and the value is an object that has an attribute
`id` identifying AWS subnet.
Examples:
You can define the values directly:subnets = {
"us-east-1a" = { id = "snet-123007" }
"us-east-1b" = { id = "snet-123008" }
}You can also use output from the `subnet_sets` module:subnets = { for k, v in module.subnet\_sets["untrust"].subnets : k => { id = v.id } } | map(object({
id = string
})) | n/a | yes |
| [tags](#input\_tags) | Map of AWS tags to apply to all the created resources. | `map(string)` | `{}` | no |
-| [targets](#input\_targets) | A list of backends accepting traffic. For Application Load Balancer all targets are of type `IP`. This is because this is the only option that allows a direct routing between a Load Balancer and a specific VMSeries' network interface. The Application Load Balancer is meant to be always public, therefore the VMSeries IPs should be from the public facing subnet. An example on how to feed this variable with data:fw\_instance\_ips = { for k, v in var.vmseries : k => module.vmseries[k].interfaces["untrust"].private\_ip }For format of `var.vmseries` check the [`vmseries` module](../vmseries/README.md). The key is the VM name. By using those keys, we can loop through all vmseries modules and take the private IP from the interface that is assigned to the subnet we require. The subnet can be identified by the subnet set name (like above). In other words, the `for` loop returns the following map:{
vm01 = "1.1.1.1"
vm02 = "2.2.2.2"
...
} | `map(string)` | n/a | yes |
+| [target\_group\_az](#input\_target\_group\_az) | Availability Zones of Target Group ('all' for target group outside of VPC) | `string` | `null` | no |
+| [targets](#input\_targets) | A list of backends accepting traffic. For Application Load Balancer all targets are of type `IP`. This is because this is the only option that allows a direct routing between a Load Balancer and a specific VMSeries' network interface. The Application Load Balancer is meant to be always public, therefore the VMSeries IPs should be from the public facing subnet. An example on how to feed this variable with data:fw\_instance\_ips = { for k, v in var.vmseries : k => module.vmseries[k].interfaces["untrust"].private\_ip }For format of `var.vmseries` check the [`vmseries` module](../vmseries). The key is the VM name. By using those keys, we can loop through all vmseries modules and take the private IP from the interface that is assigned to the subnet we require. The subnet can be identified by the subnet set name (like above). In other words, the `for` loop returns the following map:{
vm01 = "1.1.1.1"
vm02 = "2.2.2.2"
...
} | `map(string)` | n/a | yes |
| [vpc\_id](#input\_vpc\_id) | ID of the security VPC for the Load Balancer. | `string` | n/a | yes |
### Outputs
@@ -149,4 +150,5 @@ No modules.
| Name | Description |
|------|-------------|
| [lb\_fqdn](#output\_lb\_fqdn) | A FQDN for the Load Balancer. |
+| [target\_group](#output\_target\_group) | n/a |
\ No newline at end of file
diff --git a/products/terraform/docs/swfw/aws/vmseries/modules/asg.md b/products/terraform/docs/swfw/aws/vmseries/modules/asg.md
index f2d045d80..a3071e747 100644
--- a/products/terraform/docs/swfw/aws/vmseries/modules/asg.md
+++ b/products/terraform/docs/swfw/aws/vmseries/modules/asg.md
@@ -76,7 +76,8 @@ No modules.
| [global\_tags](#input\_global\_tags) | Map of AWS tags to apply to all the created resources. | `map(any)` | n/a | yes |
| [instance\_type](#input\_instance\_type) | EC2 instance type. | `string` | `"m5.xlarge"` | no |
| [interfaces](#input\_interfaces) | Map of the network interface specifications.
If "mgmt-interface-swap" bootstrap option is enabled, ensure dataplane interface `device_index` is set to 0 and the firewall management interface `device_index` is set to 1.
Available options:
- `device_index` = (Required\|int) Determines order in which interfaces are attached to the instance. Interface with `0` is attached at boot time.
- `subnet_id` = (Required\|string) Subnet ID to create the ENI in.
- `name` = (Optional\|string) Name tag for the ENI. Defaults to instance name suffixed by map's key.
- `description` = (Optional\|string) A descriptive name for the ENI.
- `create_public_ip` = (Optional\|bool) Whether to create a public IP for the ENI. Defaults to false.
- `eip_allocation_id` = (Optional\|string) Associate an existing EIP to the ENI.
- `private_ips` = (Optional\|list) List of private IPs to assign to the ENI. If not set, dynamic allocation is used.
- `public_ipv4_pool` = (Optional\|string) EC2 IPv4 address pool identifier.
- `source_dest_check` = (Optional\|bool) Whether to enable source destination checking for the ENI. Defaults to false.
- `security_group_ids` = (Optional\|list) A list of Security Group IDs to assign to this interface. Defaults to null.
Example:interfaces = {
mgmt = {
device\_index = 0
subnet\_id = aws\_subnet.mgmt.id
name = "mgmt"
create\_public\_ip = true
source\_dest\_check = true
security\_group\_ids = ["sg-123456"]
},
public = {
device\_index = 1
subnet\_id = aws\_subnet.public.id
name = "public"
create\_public\_ip = true
},
private = {
device\_index = 2
subnet\_id = aws\_subnet.private.id
name = "private"
},
] | `map(any)` | n/a | yes |
-| [lambda\_timeout](#input\_lambda\_timeout) | Amount of time Lambda Function has to run in seconds. | `number` | `10` | no |
+| [ip\_target\_groups](#input\_ip\_target\_groups) | Target groups (type IP) for load balancers, which are used by Lamda to register VM-Series IP of untrust interface | list(object({
arn = string
port = string
})) | `[]` | no |
+| [lambda\_timeout](#input\_lambda\_timeout) | Amount of time Lambda Function has to run in seconds. | `number` | `30` | no |
| [lifecycle\_hook\_timeout](#input\_lifecycle\_hook\_timeout) | How long should we wait for lambda to finish | `number` | `300` | no |
| [max\_size](#input\_max\_size) | Maximum size of the Auto Scaling Group. | `number` | `2` | no |
| [min\_size](#input\_min\_size) | Minimum size of the Auto Scaling Group. | `number` | `1` | no |
@@ -92,7 +93,7 @@ No modules.
| [ssh\_key\_name](#input\_ssh\_key\_name) | Name of AWS keypair to associate with instances | `string` | n/a | yes |
| [subnet\_ids](#input\_subnet\_ids) | List of subnet IDs associated with the Lambda function | `list(string)` | `[]` | no |
| [suspended\_processes](#input\_suspended\_processes) | List of processes to suspend for the Auto Scaling Group. The allowed values are Launch, Terminate, HealthCheck, ReplaceUnhealthy, AZRebalance, AlarmNotification, ScheduledActions, AddToLoadBalancer, InstanceRefresh | `list(string)` | `[]` | no |
-| [target\_group\_arn](#input\_target\_group\_arn) | ARN of target group for load balancer | `string` | `null` | no |
+| [target\_group\_arn](#input\_target\_group\_arn) | ARN of target group (type instance) for load balancer, which is used by ASG to register VM-Series instance | `string` | `null` | no |
| [vmseries\_ami\_id](#input\_vmseries\_ami\_id) | The AMI from which to launch the instance. Takes precedence over fw\_version and fw\_license\_type | `string` | `null` | no |
| [vmseries\_iam\_instance\_profile](#input\_vmseries\_iam\_instance\_profile) | IAM instance profile used in launch template | `string` | `""` | no |
| [vmseries\_product\_code](#input\_vmseries\_product\_code) | Product code corresponding to a chosen VM-Series license type model - by default - BYOL.
To check the available license type models and their codes, please refer to the
[VM-Series documentation](https://docs.paloaltonetworks.com/vm-series/10-0/vm-series-deployment/set-up-the-vm-series-firewall-on-aws/deploy-the-vm-series-firewall-on-aws/obtain-the-ami/get-amazon-machine-image-ids.html) | `string` | `"6njl1pau431dv1qxipg63mvah"` | no |
diff --git a/products/terraform/docs/swfw/aws/vmseries/modules/gwlb.md b/products/terraform/docs/swfw/aws/vmseries/modules/gwlb.md
index cc50ebf00..1aa4b7d18 100644
--- a/products/terraform/docs/swfw/aws/vmseries/modules/gwlb.md
+++ b/products/terraform/docs/swfw/aws/vmseries/modules/gwlb.md
@@ -70,6 +70,7 @@ No modules.
|------|-------------|------|---------|:--------:|
| [allowed\_principals](#input\_allowed\_principals) | List of AWS Principal ARNs who are allowed access to the GWLB Endpoint Service. For example `["arn:aws:iam::123456789000:root"]`. | `list(string)` | `[]` | no |
| [deregistration\_delay](#input\_deregistration\_delay) | See the `aws` provider [documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb_target_group#deregistration_delay). | `number` | `null` | no |
+| [enable\_lb\_deletion\_protection](#input\_enable\_lb\_deletion\_protection) | Whether to enable deletion protection on the gateway loadbalancer. | `bool` | `false` | no |
| [endpoint\_service\_tags](#input\_endpoint\_service\_tags) | Map of AWS tags to apply to the created GWLB Endpoint Service. These tags are applied after the `global_tags`. | `map(string)` | `{}` | no |
| [global\_tags](#input\_global\_tags) | Map of AWS tags to apply to all the created resources. | `map(string)` | `{}` | no |
| [health\_check\_enabled](#input\_health\_check\_enabled) | See the `aws` provider [documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/lb_target_group#health_check). | `bool` | `null` | no |
@@ -83,6 +84,7 @@ No modules.
| [lb\_tags](#input\_lb\_tags) | Map of AWS tags to apply to the created Load Balancer object. These tags are applied after the `global_tags`. | `map(string)` | `{}` | no |
| [lb\_target\_group\_tags](#input\_lb\_target\_group\_tags) | Map of AWS tags to apply to the created GWLB Target Group. These tags are applied after the `global_tags`. | `map(string)` | `{}` | no |
| [name](#input\_name) | Name of the created GWLB and its Target Group. Must be unique per AWS region per AWS account. | `string` | n/a | yes |
+| [stickiness\_type](#input\_stickiness\_type) | If `stickiness_type` is `null`, then attribute `enabled` is set to `false` in stickiness configuration block,
value provided in `type` is ignored and by default the Gateway Load Balancer uses 5-tuple to maintain flow stickiness to a specific target appliance.
If `stickiness_type` is not `null`, then attribute `enabled` is set to `true` in stickiness configuration block
and the stickiness `type` can be then customized by using value:
- `source_ip_dest_ip_proto` for 3-tuple (Source IP, Destination IP and Transport Protocol)
- `source_ip_dest_ip` for 2-tuple (Source IP and Destination IP) | `string` | `null` | no |
| [subnets](#input\_subnets) | Map of subnets where to create the GWLB. Each map's key is the availability zone name and each map's object has an attribute
`id` identifying AWS subnet.
Example for users of module `subnet_set`:subnets = module.subnet\_set.subnets
Example:subnets = {
"us-east-1a" = { id = "snet-123007" }
"us-east-1b" = { id = "snet-123008" }
} | map(object({
id = string
})) | n/a | yes |
| [target\_instances](#input\_target\_instances) | Map of instances to attach to the GWLB Target Group. | map(object({
id = string
})) | `{}` | no |
| [unhealthy\_threshold](#input\_unhealthy\_threshold) | The number of failed health checks required before a healthy target becomes unhealthy. Minimum 2 and maximum 10. | `number` | `3` | no |
diff --git a/products/terraform/docs/swfw/aws/vmseries/modules/nlb.md b/products/terraform/docs/swfw/aws/vmseries/modules/nlb.md
index 1f551a52e..c36d59b99 100644
--- a/products/terraform/docs/swfw/aws/vmseries/modules/nlb.md
+++ b/products/terraform/docs/swfw/aws/vmseries/modules/nlb.md
@@ -22,7 +22,7 @@ A Terraform module for deploying a Network Load Balancer in AWS cloud. This can
## Usage
-For example usage please refer to the [tgw_inbound_with_alb_nlb](../../examples/tgw_inbound_with_alb_nlb/README.md) example.
+For example usage please refer to the [tgw_inbound_with_alb_nlb](https://registry.terraform.io/modules/PaloAltoNetworks/vmseries-modules/aws/latest/examples/tgw_inbound_with_alb_nlb) example.
## Reference
@@ -71,4 +71,5 @@ No modules.
| Name | Description |
|------|-------------|
| [lb\_fqdn](#output\_lb\_fqdn) | A FQDN for the Load Balancer. |
+| [target\_group](#output\_target\_group) | n/a |
\ No newline at end of file
diff --git a/products/terraform/docs/swfw/aws/vmseries/modules/panorama.md b/products/terraform/docs/swfw/aws/vmseries/modules/panorama.md
index faa08c277..66d9d0ea2 100644
--- a/products/terraform/docs/swfw/aws/vmseries/modules/panorama.md
+++ b/products/terraform/docs/swfw/aws/vmseries/modules/panorama.md
@@ -63,6 +63,7 @@ No modules.
| [create\_public\_ip](#input\_create\_public\_ip) | If true, create an Elastic IP address for Panorama. | `bool` | `false` | no |
| [ebs\_kms\_key\_alias](#input\_ebs\_kms\_key\_alias) | The alias for the customer managed KMS key to use for volume encryption.
If this is set to `null` the default master key that protects EBS volumes will be used | `string` | `null` | no |
| [ebs\_volumes](#input\_ebs\_volumes) | List of EBS volumes to create and attach to Panorama.
Available options:
- `name` (Optional) Name tag for the EBS volume. If not provided defaults to the value of `var.name`.
- `ebs_device_name` (Required) The EBS device name to expose to the instance (for example, /dev/sdh or xvdh).
See [Device Naming on Linux Instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/device_naming.html#available-ec2-device-names) for more information.
- `ebs_size` (Optional) The size of the EBS volume in GiBs. Defaults to 2000 GiB.
- `ebs_encrypted` (Optional) If true, the Panorama EBS volume will be encrypted.
- `force_detach` (Optional) Set to true if you want to force the volume to detach. Useful if previous attempts failed, but use this option only as a last resort, as this can result in data loss.
- `skip_destroy` (Optional) Set this to true if you do not wish to detach the volume from the instance to which it is attached at destroy time, and instead just remove the attachment from Terraform state.
This is useful when destroying an instance attached to third-party volumes.
Note: Terraform must be running with credentials which have the `GenerateDataKeyWithoutPlaintext` permission on the specified KMS key
as required by the [EBS KMS CMK volume provisioning process](https://docs.aws.amazon.com/kms/latest/developerguide/services-ebs.html#ebs-cmk) to prevent a volume from being created and almost immediately deleted.
If null, the default EBS encryption KMS key in the current region is used.
Example:ebs\_volumes = [
{
name = "ebs-1"
ebs\_device\_name = "/dev/sdb"
ebs\_size = "2000"
ebs\_encrypted = true
},
{
name = "ebs-2"
ebs\_device\_name = "/dev/sdb"
ebs\_size = "2000"
ebs\_encrypted = true
},
{
name = "ebs-3"
ebs\_device\_name = "/dev/sdb"
ebs\_size = "2000"
},
]
| `list(any)` | `[]` | no |
+| [enable\_imdsv2](#input\_enable\_imdsv2) | Whether to enable IMDSv2 on the EC2 instance.
Support for this feature has been added in VM-Series Plugin [3.0.0](https://docs.paloaltonetworks.com/plugins/vm-series-and-panorama-plugins-release-notes/vm-series-plugin/vm-series-plugin-30/vm-series-plugin-300#id126d0957-95d7-4b29-9147-fff20027986e), which in turn requires PAN-OS version 10.2.0 at minimum. | `string` | `false` | no |
| [global\_tags](#input\_global\_tags) | A map of tags to assign to the resources.
If configured with a provider `default_tags` configuration block present, tags with matching keys will overwrite those defined at the provider-level." | `map(any)` | `{}` | no |
| [instance\_type](#input\_instance\_type) | EC2 instance type for Panorama. Default set to Palo Alto Networks recommended instance type. | `string` | `"c5.4xlarge"` | no |
| [name](#input\_name) | Name for the Panorama instance. | `string` | `"pan-panorama"` | no |
diff --git a/products/terraform/docs/swfw/aws/vmseries/modules/vmseries.md b/products/terraform/docs/swfw/aws/vmseries/modules/vmseries.md
index 932faa63e..64ce1f072 100644
--- a/products/terraform/docs/swfw/aws/vmseries/modules/vmseries.md
+++ b/products/terraform/docs/swfw/aws/vmseries/modules/vmseries.md
@@ -68,6 +68,7 @@ No modules.
| [ebs\_encrypted](#input\_ebs\_encrypted) | Whether to enable EBS encryption on volumes. | `bool` | `true` | no |
| [ebs\_kms\_key\_alias](#input\_ebs\_kms\_key\_alias) | The alias for the customer managed KMS key to use for volume encryption. Should be prepended with the word "alias" followed by a forward slash (alias/example-key-alias).
If `null` (the default), the default master key that protects EBS volumes will be used. | `string` | `null` | no |
| [enable\_imdsv2](#input\_enable\_imdsv2) | Whether to enable IMDSv2 on the EC2 instance.
Support for this feature has been added in VM-Series Plugin [3.0.0](https://docs.paloaltonetworks.com/plugins/vm-series-and-panorama-plugins-release-notes/vm-series-plugin/vm-series-plugin-30/vm-series-plugin-300#id126d0957-95d7-4b29-9147-fff20027986e), which in turn requires VM-Series version 10.2.0 at minimum. | `string` | `false` | no |
+| [enable\_instance\_termination\_protection](#input\_enable\_instance\_termination\_protection) | Whether to enable termination protection on the EC2 instance. | `bool` | `false` | no |
| [iam\_instance\_profile](#input\_iam\_instance\_profile) | IAM instance profile. | `string` | `null` | no |
| [instance\_type](#input\_instance\_type) | EC2 instance type. | `string` | `"m5.xlarge"` | no |
| [interfaces](#input\_interfaces) | Map of the network interface specifications.
If "mgmt-interface-swap" bootstrap option is enabled, ensure dataplane interface `device_index` is set to 0 and the firewall management interface `device_index` is set to 1.
Available options:
- `device_index` = (Required\|int) Determines order in which interfaces are attached to the instance. Interface with `0` is attached at boot time.
- `subnet_id` = (Required\|string) Subnet ID to create the ENI in.
- `name` = (Optional\|string) Name tag for the ENI. Defaults to instance name suffixed by map's key.
- `description` = (Optional\|string) A descriptive name for the ENI.
- `create_public_ip` = (Optional\|bool) Whether to create a public IP for the ENI. Defaults to false.
- `eip_allocation_id` = (Optional\|string) Associate an existing EIP to the ENI.
- `private_ips` = (Optional\|list) List of private IPs to assign to the ENI. If not set, dynamic allocation is used.
- `public_ipv4_pool` = (Optional\|string) EC2 IPv4 address pool identifier.
- `source_dest_check` = (Optional\|bool) Whether to enable source destination checking for the ENI. Defaults to false.
- `security_group_ids` = (Optional\|list) A list of Security Group IDs to assign to this interface. Defaults to null.
Example:interfaces = {
mgmt = {
device\_index = 0
subnet\_id = aws\_subnet.mgmt.id
name = "mgmt"
create\_public\_ip = true
source\_dest\_check = true
security\_group\_ids = ["sg-123456"]
},
public = {
device\_index = 1
subnet\_id = aws\_subnet.public.id
name = "public"
create\_public\_ip = true
},
private = {
device\_index = 2
subnet\_id = aws\_subnet.private.id
name = "private"
},
] | `map(any)` | n/a | yes |
diff --git a/products/terraform/docs/swfw/aws/vmseries/modules/vpc.md b/products/terraform/docs/swfw/aws/vmseries/modules/vpc.md
index a70ee81b7..e89cec5de 100644
--- a/products/terraform/docs/swfw/aws/vmseries/modules/vpc.md
+++ b/products/terraform/docs/swfw/aws/vmseries/modules/vpc.md
@@ -100,7 +100,7 @@ No modules.
| [name](#input\_name) | Name of the VPC to create or use. | `string` | n/a | yes |
| [ntp\_servers](#input\_ntp\_servers) | Specify a list of NTP server addresses for DHCP options set, default to AWS provided | `list(string)` | `[]` | no |
| [secondary\_cidr\_blocks](#input\_secondary\_cidr\_blocks) | Secondary CIDR block to assign to a new VPC. | `list(string)` | `[]` | no |
-| [security\_groups](#input\_security\_groups) | The `security_groups` variable is a map of maps, where each map represents an AWS Security Group.
The key of each entry acts as the Security Group name.
List of available attributes of each Security Group entry:
- `rules`: A list of objects representing a Security Group rule. The key of each entry acts as the name of the rule and
needs to be unique across all rules in the Security Group.
List of attributes available to define a Security Group rule:
- `description`: Security Group description.
- `type`: Specifies if rule will be evaluated on ingress (inbound) or egress (outbound) traffic.
- `cidr_blocks`: List of CIDR blocks - for ingress, determines the traffic that can reach your instance. For egress
Determines the traffic that can leave your instance, and where it can go.
Example:security\_groups = {
vmseries-mgmt = {
name = "vmseries-mgmt"
rules = {
all-outbound = {
description = "Permit All traffic outbound"
type = "egress", from\_port = "0", to\_port = "0", protocol = "-1"
cidr\_blocks = ["0.0.0.0/0"]
}
https-inbound-private = {
description = "Permit HTTPS for VM-Series Management"
type = "ingress", from\_port = "443", to\_port = "443", protocol = "tcp"
cidr\_blocks = ["10.0.0.0/8"]
}
https-inbound-eip = {
description = "Permit HTTPS for VM-Series Management from known public IPs"
type = "ingress", from\_port = "443", to\_port = "443", protocol = "tcp"
cidr\_blocks = ["100.100.100.100/32"]
}
ssh-inbound-eip = {
description = "Permit SSH for VM-Series Management from known public IPs"
type = "ingress", from\_port = "22", to\_port = "22", protocol = "tcp"
cidr\_blocks = ["100.100.100.100/32"]
}
}
}
} | `any` | `{}` | no |
+| [security\_groups](#input\_security\_groups) | The `security_groups` variable is a map of maps, where each map represents an AWS Security Group.
The key of each entry acts as the Security Group name.
List of available attributes of each Security Group entry:
- `rules`: A list of objects representing a Security Group rule. The key of each entry acts as the name of the rule and
needs to be unique across all rules in the Security Group.
List of attributes available to define a Security Group rule:
- `description`: Security Group description.
- `type`: Specifies if rule will be evaluated on ingress (inbound) or egress (outbound) traffic.
- `cidr_blocks`: List of CIDR blocks - for ingress, determines the traffic that can reach your instance. For egress
Determines the traffic that can leave your instance, and where it can go.
- `prefix_list_ids`: List of Prefix List IDs
Example:security\_groups = {
vmseries-mgmt = {
name = "vmseries-mgmt"
rules = {
all-outbound = {
description = "Permit All traffic outbound"
type = "egress", from\_port = "0", to\_port = "0", protocol = "-1"
cidr\_blocks = ["0.0.0.0/0"]
}
https-inbound-private = {
description = "Permit HTTPS for VM-Series Management"
type = "ingress", from\_port = "443", to\_port = "443", protocol = "tcp"
cidr\_blocks = ["10.0.0.0/8"]
}
https-inbound-eip = {
description = "Permit HTTPS for VM-Series Management from known public IPs"
type = "ingress", from\_port = "443", to\_port = "443", protocol = "tcp"
cidr\_blocks = ["100.100.100.100/32"]
}
ssh-inbound-eip = {
description = "Permit SSH for VM-Series Management from known public IPs"
type = "ingress", from\_port = "22", to\_port = "22", protocol = "tcp"
cidr\_blocks = ["100.100.100.100/32"]
}
https-inbound-prefix-list = {
description = "Permit HTTPS for VM-Series Management for IPs in managed prefix list"
type = "ingress", from\_port = "443", to\_port = "443", protocol = "tcp"
prefix\_list\_ids = ["pl-1a2b3c4d5e6f7g8h9i"]
}
}
}
} | `any` | `{}` | no |
| [use\_internet\_gateway](#input\_use\_internet\_gateway) | If an existing VPC is provided and has IG attached, set to `true` to reuse it. | `bool` | `false` | no |
| [vpc\_tags](#input\_vpc\_tags) | Optional map of arbitrary tags to apply to VPC resource. | `map` | `{}` | no |
| [vpn\_gateway\_amazon\_side\_asn](#input\_vpn\_gateway\_amazon\_side\_asn) | ASN for the Amazon side of the gateway. | `string` | `null` | no |
diff --git a/products/terraform/docs/swfw/aws/vmseries/reference-architectures/47d0ec0b-9080-4af2-b82b-0445e6910975.png b/products/terraform/docs/swfw/aws/vmseries/reference-architectures/47d0ec0b-9080-4af2-b82b-0445e6910975.png
new file mode 100644
index 0000000000000000000000000000000000000000..6575f7d9e35b145acb148a1359f2e7854cf90d4b
GIT binary patch
literal 227979
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