Skip to content

Commit 6f107b6

Browse files
shivashankar-vaddepallyshivashankar-vaddepally
authored
Merge pull request #509 from netscaler/readme
Refactored README to align to Red Hat guidelines
2 parents 980ed2b + e1e3d51 commit 6f107b6

1 file changed

Lines changed: 121 additions & 102 deletions

File tree

‎README.md‎

Lines changed: 121 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -1,178 +1,197 @@
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)
137

8+
## Requirements
149

15-
## Vision
10+
### Ansible version compatibility
1611

17-
The vision of the `netscaler.adc` collection is to provide a complete declarative interface to configure and manage NetScaler ADC.
12+
Tested with Ansible Core >=2.15 versions.
1813

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>
14+
### Python version compatibility
2015

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.
16+
Tested with Python >=3.11
3417

3518
## Installation
3619

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

3924
```bash
4025
ansible-galaxy collection install netscaler.adc
4126
```
4227

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

4630
```bash
4731
ansible-galaxy collection install "git+https://github.com/netscaler/ansible-collection-netscaleradc.git" [--force]
4832
```
4933

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.
34+
> `--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.
5135
52-
### Verify the installation
36+
To verify the installation, run the following command:
5337

5438
```bash
5539
ansible-galaxy collection list netscaler.adc
5640
```
5741

58-
The above command should display the following output:
42+
The above command should display the below output:
5943

6044
```text
6145
6246
# /Users/netscaleruser/.ansible/collections/ansible_collections
6347
Collection Version
6448
------------- -------
65-
netscaler.adc 2.0.x
49+
netscaler.adc 2.8.x
50+
```
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
6675
```
6776
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.
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
7998

80-
## :key: Authentication
99+
```
81100

82-
### Authenticate to NetScaler via username and password
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+
```
123+
### NetScaler Console (ADM) as a Proxy Server
83124
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`.
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.
85126
86-
Refer to the [playbook_anatomy.md](playbook_anatomy.md) and [examples](examples) directory for the sample playbooks.
127+
An example can be found in [examples/netscaler_console_as_proxy_server.yaml](https://github.com/netscaler/ansible-collection-netscaleradc/blob/main/examples/netscaler_console_as_proxy_server.yaml).
87128
88-
### Authenticate to NetScaler
129+
Refer to the [NetScaler ADM as an API proxy server](https://docs.netscaler.com/en-us/netscaler-application-delivery-management-software/current-release/adm-as-api-proxy-server.html) for more details.
89130
90-
#### Password based authentication
131+
### Examples and playbook anatomy
132+
Refer to the [sample_playboook](https://github.com/netscaler/ansible-collection-netscaleradc/tree/main/examples) and [playbook_anatomy.md](https://github.com/netscaler/ansible-collection-netscaleradc/blob/main/playbook_anatomy.md).
91133
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`.
93134
94-
#### Using `netscaler.adc.module_defaults` group
135+
### SSH_connections
95136
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:
137+
Refer to [SSH_connections examples](https://github.com/netscaler/ansible-collection-netscaleradc/tree/main/examples/ssh_connections) to know how `ansible.builtins.` plugins can be used to configure the NetScaler ADC.
97138

98-
> Refer [examples/module_default_args_action_group.yaml](./examples/module_default_args_action_group.yaml) for an example playbook.
139+
### Authentication
99140

100-
#### Passwordless via `nitro_auth_token` parameter (SESSIONID based authentication)
141+
#### Authenticate to NetScaler via username and password
101142

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`.
143+
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`.
103144

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.
145+
Refer to the [playbook_anatomy.md](https://github.com/netscaler/ansible-collection-netscaleradc/blob/main/playbook_anatomy.md) and [sessionid_based_authentication_via_login_logout.yaml](https://github.com/netscaler/ansible-collection-netscaleradc/blob/main/examples/sessionid_based_authentication_via_login_logout.yaml) example playbook.
105146

106-
> `login` module requres `username` and `password` parameters to be passed. If you do not wish to pass the username and password, refer below.
147+
> `login` module requires `username` and `password` parameters to be passed. If you do not wish to pass the username and password, refer below.
107148

108149
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.
109150

110151
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.
111152

112-
> change the `NETSCALER_NSIP`, `NETSCALER_NITRO_USER` and `NETSCALER_NITRO_PASS`
113-
114-
> Install `jq` util if not already installed.
153+
> Note: Change the `NETSCALER_NSIP`, `NETSCALER_NITRO_USER` and `NETSCALER_NITRO_PASS`. Install `jq` util if not already installed.
115154

116155
```bash
117156
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
157+
echo $echo $NETSCALER_NITRO_AUTH_TOKEN
119158
```
120159

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.
160+
### Invocation
124161

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.
162+
The credentials of the netscaler can be provided either in the playbook by hardcoding or defining in a inventory.ini file.
126163

127-
An example can be found in [examples/netscaler_console_as_proxy_server.yaml](examples/netscaler_console_as_proxy_server.yaml)
164+
#### Execution command when hosts are declared in playbook:
128165

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)
166+
```bash
167+
ansible-playbook playbook.yaml [--verbose]
168+
```
136169

137-
## Supported Ansible Versions
170+
#### Execution command hosts are declared in an inventory file:
138171

139-
This collection is tested for Ansible version 2.14 and above.
172+
```bash
173+
ansible-playbook playbook.yaml -i inventory.ini [--verbose]
174+
```
140175

141-
> Please raise issues at <https://github.com/netscaler/ansible-collection-netscaleradc/issues> if you face any issues with the collection.
176+
## Testing
142177

143-
## Features of `netscaler.adc` collection
178+
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.
144179

145-
Refer to the [features_v2.md](features_v2.md) file for the features of the `netscaler.adc` collection.
180+
## Contributing
146181

147-
## Migrating from `citrix.adc` collection to `netscaler.adc` collection
182+
For external contributions, refer the [guidelines](https://github.com/netscaler/ansible-collection-netscaleradc/blob/c8c77cb4cb3905af8b90992bc55519f9a513ed08/CONTRIBUTING.md#L4).
148183

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.
184+
## Support
150185

151-
Refer to the [migrating_from_v1_v2.md](migrating_from_v1_v2.md) file for the migration steps.
186+
For issues : https://github.com/netscaler/ansible-collection-netscaleradc/issues
152187

153-
## Supported Modules in `netscaler.adc` collection
188+
For discussions or feature requests: https://github.com/netscaler/ansible-collection-netscaleradc/discussions
154189

155-
Refer to the [supported_modules_matrix.md](supported_modules_matrix.md) file for the list of supported modules in `netscaler.adc` collection.
190+
## Release Notes
156191

157-
## SSH connection module
192+
Please refer to the [link](https://github.com/netscaler/ansible-collection-netscaleradc/blob/0438f3253b2eca084760984b6564a0a7964a128d/CHANGELOG.md) for the release notes.
158193

159-
Refer https://github.com/netscaler/ansible-collection-netscaleradc/issues/309
160194

161-
## Todo list for the `netscaler.adc` collection
195+
## License Information
162196

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
197+
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)