f5networks.f5_modules.bigip_virtual_server module – Manage LTM virtual servers on a BIG-IP
Note
This module is part of the f5networks.f5_modules collection (version 1.17.0).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install f5networks.f5_modules
.
To use it in a playbook, specify: f5networks.f5_modules.bigip_virtual_server
.
New in version 1.0.0: of f5networks.f5_modules
Parameters
Parameter |
Comments |
---|---|
When When This option is useful when the system is load balancing devices that have the same IP address. When creating a new virtual server, the default is Choices:
|
|
Allows the BIG-IP system to track the source MAC address of incoming connections and return traffic from pools to the source MAC address, regardless of the routing table. Choices:
|
|
Disables all built-in module verification checks that require BIG-IP device calls. Using this option cuts down on the number of REST calls made by this module. The trade off is that most parameters are sent as is, which requires extra care when defining them. The device is the final source of truth for such configurations, usable in cases where speed is preferred over accuracy. If set to This parameter can be used when creating new or updating existing resources. Choices:
|
|
Specifies whether the client and server SSL profiles specified by the user should be verified to be correct against the existing profiles. This is useful in cases where a large number of profiles are being added at once. Not recommended for common use. In case of duplicate profiles, or erroneous profiles, the BIG-IP throws an error. Choices:
|
|
Specifies a pool or list of pools that the virtual server uses to replicate either client-side or server-side traffic. Typically this option is used for intrusion detection. |
|
The context option for a clone pool to replicate either client-side or server-side traffic. Choices:
|
|
The pool name to which the server replicates the traffic. Only pools created on the Common partition or on the same partition as the virtual server can be used. Referencing a pool on the Common partition needs to be done in the full path format, for example, |
|
Default profile which manages the session persistence. If you want to remove the existing default persistence profile, specify an empty value; When |
|
Virtual server description. |
|
Destination IP of the virtual server. Required when When Destination can also be specified as a name for an existing Virtual Address. |
|
List of VLANs to be disabled. If the partition is not specified in the VLAN, the This parameter is mutually exclusive with the |
|
List of VLANs to enable. When a VLAN named This parameter is mutually exclusive with the |
|
Specifies the persistence profile you want the system to use if it cannot use the specified default persistence profile. If you want to remove the existing fallback persistence profile, specify an empty value; When |
|
Applies the specified AFM policy to the virtual in an enforcing way. When creating a new virtual, if this parameter is not specified, the enforced policy is disabled. |
|
Applies the specified AFM policy to the virtual in an enforcing way. A staged policy shows the results of the policy rules in the log, while not actually applying the rules to traffic. When creating a new virtual, if this parameter is not specified, the staged policy is disabled. |
|
When set to Currently there is a limitation that non-admin users cannot set metadata on the object, despite being able to create and modify virtual server objects. Setting this option to Attempting to change Choices:
|
|
Specifies the IP intelligence policy applied to the virtual server. This parameter requires a valid BIG-IP security module is provisioned, such as ASM or AFM. |
|
Specifies a network protocol name you want the system to use to direct traffic on this virtual server. When creating a new virtual server, if this parameter is not specified, the default is The Protocol setting is not available when you select Performance (HTTP) as the The value of this argument can be specified in either its numeric value, or in a select number of named values. Refer to For a list of valid IP protocol numbers, refer to https://en.wikipedia.org/wiki/List_of_IP_protocol_numbers. When Choices:
|
|
Specifies a list of rules to be applied in priority order. If you want to remove existing iRules, specify a single empty value; The order in which iRules are specified does matter, so a list that contains the same list elements but in a different order in the playbook will make changes on the device. When |
|
Specifies the destination address network mask. This parameter works with IPv4 and IPv6 addresses. This is an optional parameter which can be specified when creating or updating virtual server. If If you specify a catchall destination (for example, When the When When |
|
Arbitrary key/value pairs you can attach to a virtual server. This is useful in situations where you want to annotate a virtual to be managed by Ansible. Key names are stored as strings; this includes names that are numbers. Values for all of the keys are stored as strings; this includes values that are numbers. Data is persisted, not ephemeral. |
|
Specifies the system mirrors connections on each member of a redundant pair. When creating a new virtual server, if this parameter is not specified, the default is Choices:
|
|
Virtual server name. |
|
Device partition to manage resources on. Default: “Common” |
|
Specifies the policies for the virtual server. When |
|
Default pool for the virtual server. If you want to remove the existing pool, specify an empty value; When creating a new virtual server, and If |
|
Port of the virtual server. Required when If you do not want to specify a particular port, use the value When When In addition to specifying a port number, a select number of service names may also be provided. The string The string The string The string The string The string The string The string The string The string The string The string |
|
When When When creating a new virtual server, the default is Choices:
|
|
List of profiles (HTTP, ClientSSL, ServerSSL, etc) to apply to both sides of the connection (client-side and server-side). If you only want to apply a particular profile to the client-side of the connection, specify If you only want to apply a particular profile to the server-side of the connection, specify If If you want to remove a profile from the list of profiles currently active on the virtual, simply remove it from the If you want to add a profile to the list of profiles currently active on the virtual, simply add it to the Profiles are important. This module will fail to configure a BIG-IP if you mix up your profiles, or if you attempt to set an IP protocol which your current, or new, profiles do not support. Both this module, and BIG-IP, will report an error if this is incorrect, resembling If you are unsure what the correct profile combinations are, we suggest having a BIG-IP available in which you can make changes and copy what the correct combinations are. To use |
|
The side of the connection on which the profile should be applied. Choices:
|
|
Name of the profile. This must be specified if a context is specified. If this is not specified, it is assumed the profile item is only a name of a profile. |
|
A dict object containing connection details. |
|
Configures the auth provider for to obtain authentication tokens from the remote device. This option is really used when working with BIG-IQ devices. |
|
If You may omit this option by setting the environment variable Previously used variable Choices:
|
|
The password for the user account used to connect to the BIG-IP. You may omit this option by setting the environment variable |
|
The BIG-IP host. You may omit this option by setting the environment variable |
|
The BIG-IP server port. You may omit this option by setting the environment variable Default: 443 |
|
Specifies the timeout in seconds for communicating with the network device for either connecting or sending commands. If the timeout is exceeded before the operation is completed, the module will error. |
|
Configures the transport connection to use when connecting to the remote device. Choices:
|
|
The username to connect to the BIG-IP with. This user must have administrative privileges on the device. You may omit this option by setting the environment variable |
|
If You may omit this option by setting the environment variable Choices:
|
|
Virtual server rate limit (connections-per-second). Setting this to The valid value range is |
|
Specifies a mask, in bits, to be applied to the destination address as part of the rate limiting. The default value is The valid value range is |
|
Indicates whether the rate limit is applied per virtual object, per source address, per destination address, or some combination thereof. The default value is Choices:
|
|
Specifies a mask, in bits, to be applied to the source address as part of the rate limiting. The default value is The valid value range is |
|
Specifies the log profile applied to the virtual server. To make use of this feature, the AFM module must be licensed and provisioned. The |
|
Specify the Firewall NAT policies for the virtual server. You can specify one or more NAT policies to use. The most specific policy is used. For example, if you specify the virtual server should use the device policy and the route domain policy, the route domain policy overrides the device policy. |
|
Specifies the policy to apply a NAT policy directly to the virtual server. The virtual server NAT policy is the most specific, and overrides a route domain and device policy, if specified. To remove the policy, specify an empty string value. |
|
Specifies the virtual server uses the device NAT policy, as specified in the Firewall Options. The device policy is used if no route domain or virtual server NAT setting is specified. Choices:
|
|
Specifies the virtual server uses the route domain policy, as specified in the Route Domain Security settings. When specified, the route domain policy overrides the device policy, and is overridden by a virtual server policy. Choices:
|
|
Specifies the immediate action to take upon the receipt of the initial SYN packet if the availability status of the virtual server is Offline or Unavailable. Supported for the virtual server of Choices:
|
|
Source network address policy. When The name of a SNAT pool (like “/Common/snat_pool_name”) can be specified to enable SNAT with the specific pool. To remove SNAT, specify the word To specify automap, use the word |
|
Specifies an IP address or network from which the virtual server accepts traffic. The virtual server accepts clients only from one of these IP addresses. For this setting to function effectively, specify a value other than 0.0.0.0/0 or ::/0 (that is, any/0, any6/0). In order to maximize the utility of this setting, specify the most specific address prefixes covering all customer addresses and no others. Specify the IP address in Classless Inter-Domain Routing (CIDR) format; address/prefix, where the prefix length is in bits. For example, for IPv4, 10.0.0.1/32 or 10.0.0.0/24, and for IPv6, ffe1::0020/64 or 2001:ed8:77b5:2:10:10:100:42/64. |
|
Specifies whether the system preserves the source port of the connection. When creating a new virtual server, if this parameter is not specified, the default is Choices:
|
|
The virtual server state. If Attempting to change Choices:
|
|
Specifies the network service provided by this virtual server. When creating a new virtual server, if this parameter is not provided, the default is This value cannot be changed after it is set. When When When When When When When When When When Choices:
|
Notes
Note
For more information on using Ansible to manage F5 Networks devices see https://www.ansible.com/integrations/networks/f5.
Requires BIG-IP software version >= 12.
The F5 modules only manipulate the running configuration of the F5 product. To ensure that BIG-IP specific configuration persists to disk, be sure to include at least one task that uses the f5networks.f5_modules.bigip_config module to save the running configuration. Refer to the module’s documentation for the correct usage of the module to save your running configuration.
Examples
- name: Modify Port of the Virtual Server
bigip_virtual_server:
state: present
partition: Common
name: my-virtual-server
port: 8080
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Delete virtual server
bigip_virtual_server:
state: absent
partition: Common
name: my-virtual-server
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Add virtual server
bigip_virtual_server:
state: present
partition: Common
name: my-virtual-server
destination: 10.10.10.10
port: 443
pool: my-pool
snat: Automap
description: Test Virtual Server
profiles:
- http
- fix
- name: clientssl
context: server-side
- name: ilx
context: client-side
policies:
- my-ltm-policy-for-asm
- ltm-uri-policy
- ltm-policy-2
- ltm-policy-3
enabled_vlans:
- /Common/vlan2
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Add FastL4 virtual server
bigip_virtual_server:
destination: 1.1.1.1
name: fastl4_vs
port: 80
profiles:
- fastL4
state: present
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Add iRules to the Virtual Server
bigip_virtual_server:
name: my-virtual-server
irules:
- irule1
- irule2
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Remove one iRule from the Virtual Server
bigip_virtual_server:
name: my-virtual-server
irules:
- irule2
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Remove all iRules from the Virtual Server
bigip_virtual_server:
name: my-virtual-server
irules: ""
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Remove pool from the Virtual Server
bigip_virtual_server:
name: my-virtual-server
pool: ""
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Add metadata to virtual
bigip_virtual_server:
name: my-virtual-server
partition: Common
metadata:
ansible: 2.4
updated_at: 2017-12-20T17:50:46Z
provider:
server: lb.mydomain.com
user: admin
password: secret
delegate_to: localhost
- name: Add virtual with two profiles
bigip_virtual_server:
name: my-virtual-server
partition: Common
profiles:
- http
- tcp
provider:
server: lb.mydomain.com
user: admin
password: secret
delegate_to: localhost
- name: Remove HTTP profile from previous virtual
bigip_virtual_server:
name: my-virtual-server
partition: Common
profiles:
- tcp
provider:
server: lb.mydomain.com
user: admin
password: secret
delegate_to: localhost
- name: Add the HTTP profile back to the previous virtual
bigip_virtual_server:
name: my-virtual-server
partition: Common
profiles:
- http
- tcp
provider:
server: lb.mydomain.com
user: admin
password: secret
delegate_to: localhost
- name: Add virtual server with rate limit
bigip_virtual_server:
state: present
partition: Common
name: my-virtual-server
destination: 10.10.10.10
port: 443
pool: my-pool
snat: Automap
description: Test Virtual Server
profiles:
- http
- fix
- name: clientssl
context: server-side
- name: ilx
context: client-side
policies:
- my-ltm-policy-for-asm
- ltm-uri-policy
- ltm-policy-2
- ltm-policy-3
enabled_vlans:
- /Common/vlan2
rate_limit: 400
rate_limit_mode: destination
rate_limit_dst_mask: 32
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Add FastL4 virtual server with clone_pools
bigip_virtual_server:
destination: 1.1.1.1
name: fastl4_vs
port: 80
profiles:
- fastL4
state: present
clone_pools:
- pool_name: FooPool
context: clientside
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
- name: Add virtual with MRF router option set
bigip_virtual_server:
name: my-virtual-server
destination: 10.10.10.10
port: 443
partition: Common
profiles:
- http
- tcp
- name: noneg-ssl
context: client-side
- name: http2
context: client-side
- name: httprouter
context: all
provider:
server: lb.mydomain.net
user: admin
password: secret
delegate_to: localhost
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
The new value specifying whether address translation is on or off. Returned: changed Sample: true |
|
Specifies the autoLasthop value of the virtual server Returned: changed Sample: “enabled” |
|
Pools to which virtual server copies traffic. Returned: changed Sample: [{“context”: “clientside”, “pool_name”: “/Common/Pool1”}] |
|
Default persistence profile set on the virtual server. Returned: changed Sample: “/Common/dest_addr” |
|
New description of the virtual server. Returned: changed Sample: “This is my description” |
|
Destination of the virtual server. Returned: changed Sample: “1.1.1.1” |
|
Whether the virtual server is disabled or not. Returned: changed Sample: true |
|
List of VLANs that the virtual is disabled for. Returned: changed Sample: [“/Common/vlan1”, “/Common/vlan2”] |
|
Whether the virtual server is enabled or not. Returned: changed Sample: false |
|
List of VLANs that the virtual is enabled for. Returned: changed Sample: [“/Common/vlan5”, “/Common/vlan6”] |
|
Fallback persistence profile set on the virtual server. Returned: changed Sample: “/Common/source_addr” |
|
The new enforcing firewall policy. Returned: changed Sample: “/Common/my-enforced-fw” |
|
The new staging firewall policy. Returned: changed Sample: “/Common/my-staged-fw” |
|
The new IP Intelligence Policy assigned to the virtual. Returned: changed Sample: “/Common/ip-intelligence” |
|
The new value of the IP protocol. Returned: changed Sample: 6 |
|
iRules set on the virtual server. Returned: changed Sample: [“/Common/irule1”, “/Common/irule2”] |
|
The new value of the virtual. Returned: changed Sample: {“key1”: “foo”, “key2”: “bar”} |
|
Specifies the system mirrors connections on each member of a redundant pair. Returned: changed Sample: true |
|
List of policies attached to the virtual. Returned: changed Sample: [“/Common/policy1”, “/Common/policy2”] |
|
Pool the virtual server is attached to. Returned: changed Sample: “/Common/my-pool” |
|
Port the virtual server is configured to listen on. Returned: changed Sample: 80 |
|
The new value specifying whether port translation is on or off. Returned: changed Sample: true |
|
List of profiles set on the virtual server. Returned: changed Sample: [{“context”: “server-side”, “name”: “tcp”}, {“context”: “client-side”, “name”: “tcp-legacy”}] |
|
The maximum number of connections per second allowed for a virtual server. Returned: changed Sample: 5000 |
|
Specifies a mask, in bits, to be applied to the destination address as part of the rate limiting. Returned: changed Sample: 32 |
|
Sets the type of rate limiting to be used on the virtual server. Returned: changed Sample: “object-source” |
|
Specifies a mask, in bits, to be applied to the source address as part of the rate limiting. Returned: changed Sample: 32 |
|
The new list of security log profiles. Returned: changed Sample: [“/Common/profile1”, “/Common/profile2”] |
|
Action to take upon the receipt of the initial SYN packet if server is Offline or Unavailable. Returned: changed Sample: “drop” |
|
SNAT setting of the virtual server. Returned: changed Sample: “Automap” |
|
Source address set on the virtual server, in CIDR format. Returned: changed Sample: “1.2.3.4/32” |
|
Specifies whether the system preserves the source port of the connection. Returned: changed Sample: “change” |
Authors
Tim Rupp (@caphrim007)
Wojciech Wypior (@wojtek0806)
Nitin Khanna (@nitinthewiz)