Skip to content

Commit d2361cc

Browse files
author
Shiva Shankar Vaddepally
committed
Refactored README to align to Red Hat guidelines
1 parent 2bff663 commit d2361cc

1 file changed

Lines changed: 108 additions & 118 deletions

File tree

‎README.md‎

Lines changed: 108 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -1,178 +1,168 @@
1-
# NetScaler Ansible Collection `version2` - netscaler.adc
1+
# NetScaler ADC Collection
22

3-
[![ansible-lint](https://github.com/netscaler/ansible-collection-netscaleradc/actions/workflows/lint.yml/badge.svg)](https://github.com/netscaler/ansible-collection-netscaleradc/actions)
4-
[![ansible-test](https://github.com/netscaler/ansible-collection-netscaleradc/actions/workflows/test.yml/badge.svg)](https://github.com/netscaler/ansible-collection-netscaleradc/actions)
5-
[![collection-release](https://github.com/netscaler/ansible-collection-netscaleradc/actions/workflows/release.yml/badge.svg)](https://github.com/netscaler/ansible-collection-netscaleradc/actions)
6-
[![ah-token-refresh](https://github.com/netscaler/ansible-collection-netscaleradc/actions/workflows/ah_token_refresh.yml/badge.svg)](https://github.com/netscaler/ansible-collection-netscaleradc/actions)
7-
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/netscaler/ansible-collection-netscaleradc/badge)](https://securityscorecards.dev/viewer/?uri=github.com/netscaler/ansible-collection-netscaleradc)
3+
## Description
84

9-
> ⚠️ Note:
10-
> The earlier `citrix.adc` ansible collection is replaced with the new `netscaler.adc` ansible collection.
5+
The collection provides Ansible modules to configure and manage NetScaler ADC appliances. The modules are written using the [NITRO API](https://developer-docs.netscaler.com/en-us/adc-nitro-api/current-release.html). The modules are idempotent and can be used to configure the NetScaler ADC appliances in a declarative manner.
116

12-
> The `citrix.adc` ansible collection is backed up by a separate branch [citrix.adc](https://github.com/netscaler/ansible-collection-netscaleradc/tree/citrix.adc)
7+
## Requirements
138

9+
### Ansible version compatibility
1410

15-
## Vision
11+
Tested with Ansible Core >=2.15 versions.
1612

17-
The vision of the `netscaler.adc` collection is to provide a complete declarative interface to configure and manage NetScaler ADC.
13+
### Python version compatibility
1814

19-
If you need any feature or flexibility that is not available in the collection at the moment, please raise issues/enhancement-requests/recommendations at <https://github.com/netscaler/ansible-collection-netscaleradc/issues>
20-
21-
> :envelope: For any immediate issues or help , reach out to us at <[email protected]> !
22-
23-
## About `version1` and `version2` of the collection
24-
25-
We refer the earlier `citrix.adc` ansible collection as `version1` and the new `netscaler.adc` as `version2`.
26-
27-
This is the `version2` of the NetScaler Ansible Collection. It is a complete rewrite of the collection. The collection is not backward compatible with the `version1` of the collection.
28-
29-
`citrix.adc` collection will be deprecated soon and will not be maintained further. It is recommended to migrate to the `netscaler.adc` collection.
30-
31-
## About the `netscaler.adc` collection (version2)
32-
33-
The collection provides Ansible modules to configure and manage NetScaler ADC appliances. The modules are written using the NITRO API. The modules are idempotent and can be used to configure the NetScaler ADC appliances in declarative manner.
15+
Tested with Python >=3.11
3416

3517
## Installation
3618

37-
### ansible-galaxy
19+
### via Ansible-galaxy
20+
21+
The netscaler.adc collection can be installed with the Ansible Galaxy command-line tool:
3822

3923
```bash
4024
ansible-galaxy collection install netscaler.adc
4125
```
4226

43-
### via github (to have the latest updated which are yet to be released in ansible-galaxy)
44-
27+
### via Github (to have the latest updated which are yet to be released in ansible-galaxy)
4528

4629
```bash
4730
ansible-galaxy collection install "git+https://github.com/netscaler/ansible-collection-netscaleradc.git" [--force]
4831
```
4932

50-
> `--force` option is required if you have already installed the collection via ansible-galaxy. This will overwrite the existing collection with the latest collection from github.
33+
`--force` option is required if you have already installed the collection via ansible-galaxy. This will overwrite the existing collection with the latest collection from github.
5134

52-
### Verify the installation
35+
To verify the installation, run the following command:
5336

5437
```bash
5538
ansible-galaxy collection list netscaler.adc
5639
```
5740

58-
The above command should display the following output:
41+
The above command should display the below output:
5942

6043
```text
6144
6245
# /Users/netscaleruser/.ansible/collections/ansible_collections
6346
Collection Version
6447
------------- -------
65-
netscaler.adc 2.0.x
48+
netscaler.adc 2.8.x
6649
```
6750

68-
## Collection Modules Documentation
69-
70-
<https://netscaler.github.io/ansible-collection-netscaleradc/>
71-
72-
> You can also click on the desired module name in the [supported_modules_matrix.md](supported_modules_matrix.md) file to go to the specific module documentation
73-
74-
## Examples
75-
76-
Refer to the [examples](examples) directory for the sample playbooks.
77-
78-
Also refer [playbook_anatomy.md](playbook_anatomy.md) for the anatomy of a playbook.
79-
80-
## :key: Authentication
81-
82-
### Authenticate to NetScaler via username and password
83-
84-
Every module in the collection requires the user to authenticate to the NetScaler ADC appliance. The authentication can be done using the `nitro_user` and `nitro_pass` parameters. These parameters can also be passed as environment variables `NETSCALER_NITRO_USER` and `NETSCALER_NITRO_PASS`.
85-
86-
Refer to the [playbook_anatomy.md](playbook_anatomy.md) and [examples](examples) directory for the sample playbooks.
87-
88-
### Authenticate to NetScaler
89-
90-
#### Password based authentication
91-
92-
Every task in the collection requires the user to authenticate to the NetScaler ADC appliance. The authentication can be done using the `nsip`, `nitro_user` and `nitro_pass` parameters. These parameters can also be passed as environment variables `NETSCALER_NSIP`, `NETSCALER_NITRO_USER` and `NETSCALER_NITRO_PASS`.
93-
94-
#### Using `netscaler.adc.module_defaults` group
51+
## Usecases
52+
53+
The modules can be called by their Fully Qualified Collection Name (FQCN) such as `netscaler.adc.lbvserver`, or by their short name `netscaler.adc` if the collection is listed under the playbook's `collections` attribute:
54+
55+
### Usecase by FQCN
56+
57+
```yaml
58+
---
59+
- name: Sample lbvserver playbook
60+
hosts: demo_netscalers
61+
gather_facts: false
62+
tasks:
63+
- name: Configure lbvserver
64+
delegate_to: localhost
65+
netscaler.adc.lbvserver:
66+
nsip: "{{ nsip }}"
67+
nitro_user: "{{ nitro_user }}"
68+
nitro_pass: "{{ nitro_pass }}"
69+
nitro_protocol: "{{ nitro_protocol }}"
70+
validate_certs: false
71+
save_config: false
72+
state: present
73+
name: lb_dns_01
74+
servicetype: HTTP
75+
```
9576
96-
To avoid having to specify common parameters for all the modules in every task, you can use the `netscaler.adc.module_defaults` [module defaults](https://docs.ansible.com/ansible/devel/playbook_guide/playbooks_module_defaults.html#module-defaults-groups) group:
77+
### Usecase by declaring collection
78+
79+
```yaml
80+
---
81+
- name: Sample lbvserver playbook
82+
hosts: demo_netscalers
83+
gather_facts: false
84+
collections:
85+
- netscaler.adc
86+
tasks:
87+
- name: Configure lbvserver
88+
delegate_to: localhost
89+
lbvserver:
90+
nsip: "{{ nsip }}"
91+
nitro_user: "{{ nitro_user }}"
92+
nitro_pass: "{{ nitro_pass }}"
93+
nitro_protocol: "{{ nitro_protocol }}"
94+
validate_certs: false
95+
save_config: false
96+
name: lb_dns_01
97+
servicetype: HTTP
9798

98-
> Refer [examples/module_default_args_action_group.yaml](./examples/module_default_args_action_group.yaml) for an example playbook.
99+
```
99100

100-
#### Passwordless via `nitro_auth_token` parameter (SESSIONID based authentication)
101+
### Usecase by `netscaler.adc.module_default` group
102+
103+
```yaml
104+
---
105+
- name: Sample Playbook to use module_defaults to specify common arguments
106+
hosts: localhost
107+
gather_facts: false
108+
module_defaults:
109+
group/netscaler.adc.default_args:
110+
nsip: 10.10.10.10
111+
nitro_user: nsroot
112+
nitro_pass: verysecretpassword
113+
nitro_protocol: http
114+
validate_certs: false
115+
save_config: false
116+
tasks:
117+
- name: Sample Task | ipset
118+
delegate_to: localhost
119+
netscaler.adc.lbvserver:
120+
name: lb_dns_01
121+
servicetype: HTTP
122+
```
101123
102-
The collection also supports authentication to NetScaler ADC appliance via token. The token can be generated using the `login` module. The token can be passed to other modules using the `nitro_auth_token` parameter. The `nitro_token` parameter can also be passed as environment variable `NETSCALER_NITRO_AUTH_TOKEN`.
124+
### Authentication
103125
104-
Refer to the [playbook_anatomy.md](playbook_anatomy.md) and [sessionid_based_authentication_via_login_logout.yaml](examples/sessionid_based_authentication_via_login_logout.yaml) example playbook.
126+
#### Authenticate to NetScaler via username and password
105127
106-
> `login` module requres `username` and `password` parameters to be passed. If you do not wish to pass the username and password, refer below.
128+
Every module in the collection requires the user to authenticate to the NetScaler ADC appliance. To authenticate, provide the `nsip`, `nitro_user` and `nitro_pass` parameters directly or set them using environment variables `NETSCALER_NSIP`, `NETSCALER_NITRO_USER` and `NETSCALER_NITRO_PASS`.
107129

108-
You can use the below `curl` command to generate the token. The token can be passed to other modules using the `nitro_auth_token` parameter. The `nitro_auth_token` parameter can also be passed as environment variable `NETSCALER_NITRO_AUTH_TOKEN`. The token is valid for 60 minutes.
130+
Refer to the [playbook_anatomy.md](https://github.com/netscaler/ansible-collection-netscaleradc/blob/c8c77cb4cb3905af8b90992bc55519f9a513ed08/playbook_anatomy.md#L4) and [examples](https://github.com/netscaler/ansible-collection-netscaleradc/tree/c8c77cb4cb3905af8b90992bc55519f9a513ed08/examples) directory for the sample playbooks.
109131

110-
The below command also uses `jq` to parse the JSON output and store the `sessionid` in the `NETSCALER_NITRO_AUTH_TOKEN` environment variable, so that it can be used by other modules.
132+
### Invocation
111133

112-
> change the `NETSCALER_NSIP`, `NETSCALER_NITRO_USER` and `NETSCALER_NITRO_PASS`
134+
The credentials of the netscaler can be provided either in the playbook by hardcoding or defining in a inventory.ini file.
113135

114-
> Install `jq` util if not already installed.
136+
#### Execution command when hosts are declared in playbook:
115137

116138
```bash
117-
export NETSCALER_NITRO_AUTH_TOKEN=$(curl -X POST -H "Content-Type:application/json" --insecure --silent https://NETSCALER_NSIP/nitro/v1/config/login -d '{"login":{"username":"NETSCALER_NITRO_USER", "password":"NETSCALER_NITRO_PASS"}}' | jq .sessionid)
118-
echo $NETSCALER_NITRO_AUTH_TOKEN
139+
ansible-playbook playbook.yaml [--verbose]
119140
```
120141

121-
## NetScaler Console (ADM) as a Proxy Server
122-
123-
Refer to the [NetScaler ADM as an API proxy server](https://docs.netscaler.com/en-us/citrix-application-delivery-management-software/current-release/adm-as-api-proxy-server.html) for more details.
124-
125-
The collection supports configuring NetScaler Console as a proxy server. This is useful when you have multiple NetScaler ADC appliances and you want to manage them using a single NetScaler Console.
142+
#### Execution command hosts are declared in an inventory file:
126143

127-
An example can be found in [examples/netscaler_console_as_proxy_server.yaml](examples/netscaler_console_as_proxy_server.yaml)
128-
129-
Also, refer to the [playbook_anatomy.md](playbook_anatomy.md#netscaler-console-as-an-api-proxy-server) for more details.
130-
131-
### Steps to configure NetScaler Console as a proxy server
132-
133-
1. Login to NetScaler Console and get the session ID
134-
2. Use the session ID in the subsequent tasks to configure the managed NetScalers via the NetScaler Console as a proxy server
135-
3. Logout from the NetScaler Console (optional)
136-
137-
## Supported Ansible Versions
138-
139-
This collection is tested for Ansible version 2.14 and above.
140-
141-
> Please raise issues at <https://github.com/netscaler/ansible-collection-netscaleradc/issues> if you face any issues with the collection.
144+
```bash
145+
ansible-playbook playbook.yaml -i inventory.ini [--verbose]
146+
```
142147

143-
## Features of `netscaler.adc` collection
148+
## Testing
144149

145-
Refer to the [features_v2.md](features_v2.md) file for the features of the `netscaler.adc` collection.
150+
The collection is tested using Github Actions. To know more about testing, please refer the [link]([https://github.com/netscaler/ansible-collection-netscaleradc/.github/workflow) to know more.
146151

147-
## Migrating from `citrix.adc` collection to `netscaler.adc` collection
152+
## Contributing
148153

149-
> Both `citrix.adc` and `netscaler.adc` can be used in the same Ansible playbook. However, it is recommended to migrate to `netscaler.adc` collection.
154+
For external contributions, refer the [guidelines](https://github.com/netscaler/ansible-collection-netscaleradc/blob/c8c77cb4cb3905af8b90992bc55519f9a513ed08/CONTRIBUTING.md#L4).
150155

151-
Refer to the [migrating_from_v1_v2.md](migrating_from_v1_v2.md) file for the migration steps.
156+
## Support
152157

153-
## Supported Modules in `netscaler.adc` collection
158+
For issues : [Issues](https://github.com/netscaler/ansible-collection-netscaleradc/issues)
154159

155-
Refer to the [supported_modules_matrix.md](supported_modules_matrix.md) file for the list of supported modules in `netscaler.adc` collection.
160+
For discussions or feature requests: [Discussions or feature request](https://github.com/netscaler/ansible-collection-netscaleradc/issues)
156161

157-
## SSH connection module
162+
## Release Notes
158163

159-
Refer https://github.com/netscaler/ansible-collection-netscaleradc/issues/309
164+
Please refer to the [link](https://github.com/netscaler/ansible-collection-netscaleradc/blob/0438f3253b2eca084760984b6564a0a7964a128d/CHANGELOG.md) for the release notes.
160165

161-
## Todo list for the `netscaler.adc` collection
166+
## License Information
162167

163-
- [x] Support for `nitro_auth_token` parameter in all modules.
164-
- [x] Update supported matrix to have documentation links
165-
- [x] Add appropriate license to the collection.
166-
- [x] Upload the collection to Ansible Galaxy.
167-
- [x] Support configuring ADC with ADM as proxy. Refer to [NetScaler ADM as an API proxy server](https://docs.netscaler.com/en-us/citrix-application-delivery-management-software/current-release/adm-as-api-proxy-server.html) for more details.
168-
- [ ] Implement SSH connection module - Refer https://github.com/netscaler/ansible-collection-netscaleradc/issues/309
169-
- [ ] Support for generic modules similar to `citrix.adc.nitro_request` and `citrix.adc.nitro_resource`?
170-
- [ ] migration tool to convert `citrix.adc` playbooks (including generic `citrix.adc.nitro_request` and `citrix.adc.nitro_resource` modules) to `netscaler.adc` modules
171-
- [ ] Add more examples
172-
- [ ] Write a python script which converts examples/playbook.yaml to module's EXAMPLE documentation
173-
- [ ] Test modules against all NetScaler ADC versions.
174-
- [x] Test modules againsts ansible versions 2.9+
175-
- [x] Configure GitHub Actions to automate the collection build and release process.
176-
- [ ] Configure GitHub Actions to automate the collection testing process.
177-
- [x] Configure GitHub Actions to automate the collection linting process.
178-
- [x] Collect NetScaler info (version, etc) and store it in the `facts` dictionary
168+
The collection uses MIT License. You can refer the [link](https://github.com/netscaler/ansible-collection-netscaleradc/blob/0438f3253b2eca084760984b6564a0a7964a128d/LICENSE) to view license information.

0 commit comments

Comments
 (0)