oci_security_list - Create,update and delete OCI Security List¶
New in version 2.5.
Synopsis¶
- Creates OCI Security List
- Update OCI Security List, if present, with a new display name
- Update OCI Security List, if present, with ingress/egress security rules
- Delete OCI Security List, if present.
Requirements¶
The below requirements are needed on the host that executes this module.
- python >= 2.6
- Python SDK for Oracle Cloud Infrastructure https://oracle-cloud-infrastructure-python-sdk.readthedocs.io
Parameters¶
Parameter | Choices/Defaults | Comments | |
---|---|---|---|
api_user |
The OCID of the user, on whose behalf, OCI APIs are invoked. If not set, then the value of the OCI_USER_OCID environment variable, if any, is used. This option is required if the user is not specified through a configuration file (See
config_file_location ). To get the user's OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm. |
||
api_user_fingerprint |
Fingerprint for the key pair being used. If not set, then the value of the OCI_USER_FINGERPRINT environment variable, if any, is used. This option is required if the key fingerprint is not specified through a configuration file (See
config_file_location ). To get the key pair's fingerprint value please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm. |
||
api_user_key_file |
Full path and filename of the private key (in PEM format). If not set, then the value of the OCI_USER_KEY_FILE variable, if any, is used. This option is required if the private key is not specified through a configuration file (See
config_file_location ). If the key is encrypted with a pass-phrase, the api_user_key_pass_phrase option must also be provided. |
||
api_user_key_pass_phrase |
Passphrase used by the key referenced in
api_user_key_file , if it is encrypted. If not set, then the value of the OCI_USER_KEY_PASS_PHRASE variable, if any, is used. This option is required if the key passphrase is not specified through a configuration file (See config_file_location ). |
||
auth_type |
|
The type of authentication to use for making API requests. By default
auth_type="api_key" based authentication is performed and the API key (see api_user_key_file) in your config file will be used. If this 'auth_type' module option is not specified, the value of the OCI_ANSIBLE_AUTH_TYPE, if any, is used. Use auth_type="instance_principal" to use instance principal based authentication when running ansible playbooks within an OCI compute instance. |
|
compartment_id |
Identifier of the compartment under which this security List would be created. Mandatory for create operation.Optional for delete and update. Mutually exclusive with security_list_id.
|
||
config_file_location |
Path to configuration file. If not set then the value of the OCI_CONFIG_FILE environment variable, if any, is used. Otherwise, defaults to ~/.oci/config.
|
||
config_profile_name |
Default: DEFAULT
|
The profile to load from the config file referenced by
config_file_location . If not set, then the value of the OCI_CONFIG_PROFILE environment variable, if any, is used. Otherwise, defaults to the "DEFAULT" profile in config_file_location . |
|
defined_tags |
Defined tags for this resource. Each key is predefined and scoped to a namespace. For more information, see https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm.
|
||
display_name |
Name of the Security List. A user friendly name. Does not have to be unique, and could be changed. If not specified, a default name would be provided.
aliases: name |
||
egress_security_rules |
Rules for allowing egress IP packets.
|
||
icmp_options |
Valid only for ICMP. Use to specify a particular ICMP type and code as defined in u'https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml'. If you specify ICMP as the protocol but omit this object, then all ICMP types and codes are allowed. If you do provide this object, the type is required and the code is optional. To enable MTU negotiation for ingress internet traffic, make sure to allow type 3 Destination Unreachable code 4 Fragmentation Needed and Do not Fragment was Set. If you need to specify multiple codes for a single type, create a separate security list rule for each.
|
||
udp_options |
Valid only for UDP. Use to specify particular destination ports for UDP rules. If UDP specified as the protocol but omit this object, then all destination ports are allowed.
|
||
is_stateless |
|
A stateless rule allows traffic in one direction. Remember to add a corresponding stateless rule in the other direction if you need to support bidirectional traffic. For example, if egress traffic allows TCP destination port 80, there should be an ingress rule to allow TCP source port 80. Defaults to false, which means the rule is stateful and a corresponding rule is not necessary for bidirectional traffic.
|
|
tcp_options |
Valid only for TCP. Use to specify particular destination ports for TCP rules. If TCP specified as the protocol but omit this object, then all destination ports are allowed.
|
||
destination
required |
The destination CIDR block for the egress rule. This is the range of IP addresses that a packet originating from the instance can go to.
|
||
protocol
required |
|
Specify either all or an IPv4 protocol number as defined in u'https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml' Options are supported only for ICMP 1, TCP 6, and UDP 17.
|
|
force_create
bool |
|
Whether to attempt non-idempotent creation of a resource. By default, create resource is an idempotent operation, and doesn't create the resource if it already exists. Setting this option to true, forcefully creates a copy of the resource, even if it already exists.This option is mutually exclusive with key_by.
|
|
freeform_tags |
Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. For more information, see https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/resourcetags.htm.
|
||
ingress_security_rules |
Rules for allowing ingress IP packets.
|
||
source
required |
The source CIDR block for the ingress rule. This is the range of IP addresses that a packet coming into the instance can come from.
|
||
icmp_options |
Valid only for ICMP. Use to specify a particular ICMP type and code as defined in u'https://www.iana.org/assignments/icmp-parameters/icmp-parameters.xhtml'. If you specify ICMP as the protocol but omit this object, then all ICMP types and codes are allowed. If you do provide this object, the type is required and the code is optional. To enable MTU negotiation for ingress internet traffic, make sure to allow type 3 Destination Unreachable code 4 Fragmentation Needed and Do not Fragment was Set. If you need to specify multiple codes for a single type, create a separate security list rule for each.
|
||
udp_options |
Valid only for UDP. Use to specify particular destination ports for UDP rules. If UDP specified as the protocol but omit this object, then all destination ports are allowed.
|
||
is_stateless |
|
A stateless rule allows traffic in one direction. Remember to add a corresponding stateless rule in the other direction if you need to support bidirectional traffic. For example, if ingress traffic allows TCP destination port 80, there should be an egress rule to allow TCP source port 80. Defaults to false, which means the rule is stateful and a corresponding rule is not necessary for bidirectional traffic.
|
|
tcp_options |
Valid only for TCP. Use to specify particular destination ports for TCP rules. If TCP specified as the protocol but omit this object, then all destination ports are allowed.
|
||
protocol
required |
|
Specify either all or an IPv4 protocol number as defined in u'https://www.iana.org/assignments/protocol-numbers/protocol-numbers.xhtml' Options are supported only for ICMP 1, TCP 6, and UDP 17.
|
|
key_by |
The list of comma-separated attributes of this resource which should be used to uniquely identify an instance of the resource. By default, all the attributes of a resource except freeform_tags are used to uniquely identify a resource.
|
||
purge_security_rules
bool |
|
Purge security rules from security list which are not present in the provided group security list. If purge_security_rules=no, provided security rules would be appended to existing security rules.
|
|
region |
The Oracle Cloud Infrastructure region to use for all OCI API requests. If not set, then the value of the OCI_REGION variable, if any, is used. This option is required if the region is not specified through a configuration file (See
config_file_location ). Please refer to https://docs.us-phoenix-1.oraclecloud.com/Content/General/Concepts/regions.htm for more information on OCI regions. |
||
security_list_id |
Identifier of the Security List. Mandatory for delete and update.
aliases: id |
||
state |
|
Create,update or delete Security List. For state=present, if it does not exists, it gets created. If exists, it gets updated.
|
|
tenancy |
OCID of your tenancy. If not set, then the value of the OCI_TENANCY variable, if any, is used. This option is required if the tenancy OCID is not specified through a configuration file (See
config_file_location ). To get the tenancy OCID, please refer https://docs.us-phoenix-1.oraclecloud.com/Content/API/Concepts/apisigningkey.htm |
||
vcn_id |
Identifier of the Virtual Cloud Network to which the security List should be attached. Mandatory for create operation. Optional for delete and update. Mutually exclusive with security_list_id.
|
||
wait
bool |
|
Whether to wait for create or delete operation to complete.
|
|
wait_timeout |
Default: 1200
|
Time, in seconds, to wait when wait=yes.
|
|
wait_until |
The lifecycle state to wait for the resource to transition into when wait=yes. By default, when wait=yes, we wait for the resource to get into ACTIVE/ATTACHED/AVAILABLE/PROVISIONED/ RUNNING applicable lifecycle state during create operation & to get into DELETED/DETACHED/ TERMINATED lifecycle state during delete operation.
|
Notes¶
Note
- For OCI python sdk configuration, please refer to https://oracle-cloud-infrastructure-python-sdk.readthedocs.io/en/latest/configuration.html
Examples¶
# Note: These examples do not set authentication details.
# Create/update Security List
- name: Create a security list with rules
oci_security_list:
name: 'ansible_sec_list'
compartment_id: 'ocid.comprtment..aa'
vcn_id: 'ocid1.vcn..aa'
state: 'present'
freeform_tags:
region: 'east'
defined_tags:
features:
capacity: 'medium'
ingress_security_rules:
- source: '0.0.0.0/0'
is_stateless: False
protocol: '6'
tcp_options:
destination_port_range:
min: '22'
max: '22'
- source: '0.0.0.0/0'
is_stateless: False
protocol: '1'
icmp_options:
code: 4
type: 3
egress_security_rules:
- destination: '0.0.0.0/0'
protocol: 'all'
- name: Update a security list by purging existing ingress rules
oci_security_list:
security_list_id: 'ocid1.securitylist.aa'
ingress_security_rules:
- source: '10.0.0.0/8'
is_stateless: False
protocol: '6'
tcp_options:
destination_port_range:
min: '25'
max: '30'
purge_security_rules: 'yes'
state: 'present'
# Delete a security list
- name: Delete a security list
oci_security_list:
id: 'ocid1.securitylist.aa'
state: 'absent'
Return Values¶
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description | |
---|---|---|---|
security_list
complex
|
success |
Attributes of the created/updated Security List. For delete, deleted Security List description will be returned.
Sample:
{'lifecycle_state': 'AVAILABLE', 'egress_security_rules': [{'icmp_options': None, 'udp_options': None, 'is_stateless': None, 'tcp_options': None, 'destination': '0.0.0.0/0', 'protocol': 'all'}], 'display_name': 'ansible_security_list_one', 'compartment_id': 'ocid1.compartment.oc1..xxxxxEXAMPLExxxxx', 'vcn_id': 'ocid1.vcn.oc1.phx.xxxxxEXAMPLExxxxx', 'defined_tags': {'features': {'capacity': 'medium'}}, 'freeform_tags': {'region': 'east'}, 'time_created': '2017-11-24T05:33:44.779000+00:00', 'ingress_security_rules': [{'source': '0.0.0.0/0', 'icmp_options': None, 'udp_options': None, 'is_stateless': False, 'tcp_options': {'source_port_range': None, 'destination_port_range': {'max': 22, 'min': 22}}, 'protocol': '6'}, {'source': '0.0.0.0/0', 'icmp_options': {'code': 4, 'type': 3}, 'udp_options': None, 'is_stateless': False, 'tcp_options': None, 'protocol': '1'}, {'source': '10.0.0.0/16', 'icmp_options': {'code': None, 'type': 3}, 'udp_options': None, 'is_stateless': False, 'tcp_options': None, 'protocol': '1'}], 'id': 'ocid1.securitylist.oc1.phx.xxxxxEXAMPLExxxxx'}
|
|
vcn_id
string
|
always |
Identifier of the Virtual Cloud Network to which the Security List is attached.
Sample:
ocid1.vcn..ixcd
|
|
egress_security_rules
list
|
always |
Rules for allowing egress IP packets
Sample:
[{'icmp_options': None, 'udp_options': None, 'is_stateless': None, 'tcp_options': None, 'destination': '0.0.0.0/0', 'protocol': 'all'}]
|
|
display_name
string
|
always |
Name assigned to the Security List during creation
Sample:
ansible_security_list
|
|
compartment_id
string
|
always |
The identifier of the compartment containing the Security List
Sample:
ocid1.compartment.oc1.xzvf..oifds
|
|
lifecycle_state
string
|
always |
The current state of the Security List
Sample:
AVAILABLE
|
|
time_created
datetime
|
always |
Date and time when the Security List was created, in the format defined by RFC3339
Sample:
2016-08-25 21:10:29.600000
|
|
ingress_security_rules
list
|
always |
Rules for allowing ingress IP packets
Sample:
[{'source': '0.0.0.0/0', 'icmp_options': None, 'udp_options': None, 'is_stateless': None, 'tcp_options': {'source_port_range': None, 'destination_port_range': {'max': 22, 'min': 22}}, 'protocol': '6'}]
|
|
id
string
|
always |
Identifier of the Security List
Sample:
ocid1.securitylist.oc1.axdf
|
Status¶
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Author¶
- Debayan Gupta(@debayan_gupta)
Hint
If you notice any issues in this documentation you can edit this document to improve it.