everpure.flasharray.purefa_tls_policy module – Manage Everpure FlashArray TLS policies

Note

This module is part of the everpure.flasharray collection (version 1.46.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 everpure.flasharray. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: everpure.flasharray.purefa_tls_policy.

New in everpure.flasharray 1.46.0

Synopsis

  • Create, update, rename or delete TLS policies on Everpure FlashArrays and manage the file servers they are attached to.

  • A TLS policy is a reusable inbound TLS configuration. It controls the server certificate the array presents, the minimum TLS version and ciphers permitted, optional mutual-TLS verification of client certificates, and which protocols require TLS.

  • In this release the only policy-aware protocol is NFS. A TLS policy attached to a file server applies to all of that server’s VIFs.

  • File servers are managed by everpure.flasharray.purefa_server. This module only attaches and detaches an existing TLS policy to and from them; it does not create or alter the servers themselves.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 3.3

  • purestorage >= 1.19

  • py-pure-client >= 1.88.0

  • netaddr

  • requests

  • pycountry

  • urllib3

Parameters

Parameter

Comments

api_token

string

FlashArray API token for admin privileged user.

appliance_certificate

string

Name of the certificate the array presents as the server certificate in TLS negotiation with clients connecting to the file servers this policy applies to.

Required when creating a policy.

client_certificates_required

boolean

If true, all clients must present a client certificate during TLS negotiation; failure to do so is rejected.

If false, client certificates are optional.

Choices:

  • false

  • true

client_id

string

added in everpure.flasharray 1.43.0

ID of the API Client that issues the identity token.

Used with private_key_file.

context

string

Name of fleet member on which to perform the operation.

This requires the array receiving the request is a member of a fleet and the context name to be a member of the same fleet.

Default: ""

disable_warnings

boolean

added in everpure.flasharray 1.29.0

Disable insecure certificate warnings in debug logs

Choices:

  • false ← (default)

  • true

disabled_tls_ciphers

list / elements=string

List of TLS ciphers to disable.

enabled

boolean

If true the policy is enabled.

Defaults to true on creation if not specified.

Choices:

  • false

  • true

enabled_tls_ciphers

list / elements=string

List of TLS ciphers to enable.

When supplied, only these ciphers will be enabled.

The literal value default lets the array manage the enabled ciphers and adjust them across software upgrades.

Cipher names are validated by the array. When ciphers are listed and min_tls_version is 1.3, the array requires TLS_AES_128_GCM_SHA256 to be among them.

When min_tls_version is default and ciphers are listed, the list must also include TLS 1.2 ciphers; a TLS 1.3 only list is rejected.

fa_url

string

FlashArray management IPv4 address or Hostname.

id_token

string

added in everpure.flasharray 1.43.0

A pre-signed JWT to authenticate with, as an alternative to api_token.

The token is exchanged by the array for a short-lived access token.

Requires a matching API Client to be registered on the array (see everpure.flasharray.purefa_apiclient).

issuer

string

added in everpure.flasharray 1.43.0

The API Client’s trusted identity issuer registered on the array.

Used with private_key_file.

key_id

string

added in everpure.flasharray 1.43.0

Key ID of the API Client that issues the identity token.

Used with private_key_file.

min_tls_version

string

Minimum TLS version permitted for inbound connections.

default lets the array pick a recommended minimum that may shift across software upgrades.

Choices:

  • "default"

  • "1.2"

  • "1.3"

name

string / required

Name of the TLS policy.

private_key_file

string

added in everpure.flasharray 1.43.0

Path to the PEM RSA private key used to sign an identity token, as an alternative to api_token.

Requires client_id, key_id, issuer and username.

private_key_password

string

added in everpure.flasharray 1.43.0

Password protecting private_key_file, if encrypted.

rename

string

Value to rename the specified TLS policy to.

The destination name must not already be in use.

servers

list / elements=string

Desired set of file servers this policy should be attached to.

Declarative. File servers in the list that are not attached to this policy are attached, and servers attached to this policy that are not in the list are detached. An empty list detaches the policy from all servers.

Omit the option to leave the policy’s server attachments alone. Server attachments change only when this option is named explicitly.

Attaching a policy that enforces TLS (see tls_enforced_for) forces TLS on the affected protocol across all of the server’s VIFs the moment the task runs, so existing plaintext clients stop connecting until they switch to TLS.

A file server has at most one TLS policy. Attaching this policy to a server that already has a different one fails; detach the existing policy first.

A TLS policy cannot be attached to a file server that has S3 VIFs.

state

string

Define whether the TLS policy should exist or not.

Choices:

  • "absent"

  • "present" ← (default)

tls_enforced_for

list / elements=string

List of protocols for which TLS is required. A protocol not in the list is not forced to negotiate TLS by this policy.

Only nfs is valid in this release. Values are matched case-insensitively.

Use an empty list to stop enforcing TLS for any protocol.

Enforcement takes effect only when the policy is attached to a file server (see servers); at that point existing plaintext clients of the protocol stop connecting until they switch to TLS.

trusted_client_certificate_authority

string

Name of the certificate used to verify certificates presented by clients when verify_client_certificate_trust is true.

Must name an external certificate. An appliance certificate is rejected by the array.

Set to an empty string ("") to clear a previously assigned trusted CA reference. This only applies on update; on create an empty string is treated the same as omitting the parameter.

username

string

added in everpure.flasharray 1.43.0

Username the issued token should be granted to.

Must be a valid user on the array. Used with private_key_file.

verify_client_certificate_trust

boolean

If true, certificates presented by clients undergo strict trust verification using the certificate referenced by trusted_client_certificate_authority.

Choices:

  • false

  • true

Notes

Note

  • Requires Purity//FA REST API 2.54 or higher, which is where TLS policies and the server-policy attachment first appear.

  • This module requires the py-pure-client Python library.

  • Additional Python libraries may be required for specific modules.

  • You must set PUREFA_URL and PUREFA_API environment variables if fa_url and api_token arguments are not passed to the module directly.

  • Token-based authentication (id_token, or private_key_file with client_id, key_id, issuer and username) may be used as an alternative to api_token, and requires a matching API Client registered on the array via everpure.flasharray.purefa_apiclient.

Examples

- name: Create a server-authenticated NFS TLS policy
  everpure.flasharray.purefa_tls_policy:
    name: nfs_tls_policy
    appliance_certificate: nfs_server_cert
    min_tls_version: '1.3'
    tls_enforced_for:
      - nfs
    enabled_tls_ciphers:
      - TLS_AES_256_GCM_SHA384
      - TLS_CHACHA20_POLY1305_SHA256
      - TLS_AES_128_GCM_SHA256
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Create a mutual-TLS policy for NFS
  everpure.flasharray.purefa_tls_policy:
    name: nfs_mtls_policy
    appliance_certificate: nfs_server_cert
    tls_enforced_for:
      - nfs
    client_certificates_required: true
    verify_client_certificate_trust: true
    trusted_client_certificate_authority: nfs_client_ca
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Raise the minimum TLS version without touching anything else
  everpure.flasharray.purefa_tls_policy:
    name: nfs_tls_policy
    min_tls_version: '1.3'
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Attach a TLS policy to a set of file servers
  everpure.flasharray.purefa_tls_policy:
    name: nfs_tls_policy
    servers:
      - filesvr1
      - filesvr2
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Detach a TLS policy from all file servers
  everpure.flasharray.purefa_tls_policy:
    name: nfs_tls_policy
    servers: []
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Clear the trusted client CA and disable client verification
  everpure.flasharray.purefa_tls_policy:
    name: nfs_mtls_policy
    verify_client_certificate_trust: false
    trusted_client_certificate_authority: ""
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Disable a TLS policy without deleting it
  everpure.flasharray.purefa_tls_policy:
    name: nfs_tls_policy
    enabled: false
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Rename a TLS policy
  everpure.flasharray.purefa_tls_policy:
    name: nfs_tls_policy
    rename: nfs_tls_policy_v2
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

- name: Delete an unattached TLS policy
  everpure.flasharray.purefa_tls_policy:
    name: nfs_tls_policy
    state: absent
    fa_url: 10.10.10.2
    api_token: e31060a7-21fc-e277-6240-25983c6c4592

Authors

  • Everpure Ansible Team (@avk)