Skip to content
This repository was archived by the owner on Dec 1, 2023. It is now read-only.

Commit 598748f

Browse files
rfitzhughrfitzhugh
authored
Update and rename quickstart.md to quick-start.md
1 parent e0715ce commit 598748f

File tree

2 files changed

+321
-1
lines changed

2 files changed

+321
-1
lines changed

‎docs/quick-start.md

+321
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,321 @@
1+
# PowerShell Backup Validation
2+
This project is used to provide a framework for serial and parallel application testing against workloads that have been protected by Rubrik's Cloud Data Management platform.
3+
4+
## Abstract
5+
As virtual machines running in a VMware environment are backed up and cataloged by Rubrik, each backup or "snapshot" can be Live Mounted for testing and development purposes. This allows for an instant clone to be created that is hosted on the Rubrik filesystem layer and executed on an available ESXi host. A Live Mount takes up minimal space on the Rubrik filesystem because only incoming writes to the guest filesystem need be tracked. Because of this, the Live Mount technology is the perfect solution for quickly bringing up one or more virtual machines for validating the protected applications and services can be restored in the event of a production failure, outage, or disaster.
6+
7+
## Prerequisites
8+
9+
* [PowerShell](https://aka.ms/getps6)
10+
* [Rubrik PowerShell Module](https://www.powershellgallery.com/packages/Rubrik/)
11+
* [VMware PowerCLI](https://www.powershellgallery.com/packages/VMware.PowerCLI/)
12+
* [InvokeBuild](https://www.powershellgallery.com/packages/InvokeBuild/)
13+
14+
## Installation
15+
Once you have PowerShell installed on your system you can install the required modules by executing the following PowerShell commands:
16+
17+
```
18+
Install-Module -Name Rubrik -Scope CurrentUser
19+
Install-Module -Name VMware.PowerCLI -Scope CurrentUser
20+
Install-Module -Name InvokeBuild -Scope CurrentUser
21+
```
22+
![alt text](/img/image1.png)
23+
Sample output of Install-Module cmdlet
24+
25+
This will install the modules in the current user scope and will not require local administrative privileges. If you would like to install the modules to be used for all users on a system the following commands can be executed:
26+
27+
```
28+
Install-Module -Name Rubrik -Scope AllUsers
29+
Install-Module -Name VMware.PowerCLI -Scope AllUsers
30+
Install-Module -Name InvokeBuild -Scope AllUsers
31+
```
32+
33+
## Verify installation
34+
We can use the `Get-Module` cmdlet to verify if a module is successfully installed:
35+
36+
```
37+
'Rubrik', 'VMware.PowerCLI', 'InvokeBuild' | ForEach-Object {
38+
if (Get-Module -ListAvailable -Name $_) {
39+
'{0} module is successfully installed' -f $_
40+
} else {
41+
'{0} module is not installed' -f $_
42+
}
43+
}
44+
```
45+
46+
![alt text](/img/image2.png)
47+
The output shows that all modules are successfully installed on this system.
48+
49+
## Components
50+
In order to get started with Backup Validation there are several components that you need to understand. The PowerShell Modules that are required to run and connect to both vCenter cluster and Rubrik cluster, and the InvokeBuild module that will execute the build tasks.
51+
52+
Then we will move on the different configuration and credential files and how these files tie into the backup validation process.
53+
54+
Finally, we will look at the `.build.ps1` file, what it contains and how we can make additions to this.
55+
56+
### PowerShell Modules
57+
This use case leverages several PowerShell modules, outlined in this section.
58+
59+
#### Rubrik SDK for PowerShell
60+
Rubrik’s API first architecture enables organizations to embrace and integrate Rubrik functionality into their existing automation processes. While Rubrik APIs can be consumed natively, companies are at various stages in their automation journey with different levels of automation knowledge on staff. The Rubrik SDK for PowerShell is a project that provides a Microsoft PowerShell module for managing and monitoring Rubrik's Cloud Data Management fabric by way of published RESTful APIs.
61+
62+
#### VMware PowerCLI
63+
VMware PowerCLI is a PowerShell module built by VMware. It provides a command-line and scripting tool with hundreds of cmdlets to manage and automate tasks using PowerShell. It is available in the PowerShell Gallery, which makes it easy to install and update.
64+
65+
#### InvokeBuild
66+
Using the InvokeBuild framework, this project allows for an administrator to declare the topology of an application across one or more virtual machines. The entire collection of virtual machines is Live Mounted as a group and a battery of user-defined tests are applied. Upon the completion of the tests, the Live Mounts are removed, and a summary of results are displayed.
67+
68+
### Configuration
69+
There are three main points of configuration that we will use for Backup Validation which we will go over in details and showcase the example configuration that we have made available.
70+
71+
* Environment JSON files
72+
* Config JSON files
73+
* Identity XML files
74+
75+
### Environment JSON Files
76+
The `Environment` folder contains JSON files that describe the Rubrik Cluster and vCenter Server information. This specifies either the IP address or the FQDN of both the Rubrik cluster and the vCenter cluster. It also specifies the credentials that will be used to connect to either cluster.
77+
78+
A sample configuration looks like:
79+
80+
```
81+
{
82+
"rubrikServer": "172.17.28.11",
83+
"rubrikCred": "rubrikCred.xml",
84+
"vmwareServer": "172.17.48.22",
85+
"vmwareCred": "vmwareCred.xml"
86+
}
87+
```
88+
89+
### Config JSON Files
90+
The `Config` folder contains JSON files that describe the virtual machines being tested. A sample configuration looks like:
91+
92+
```
93+
{
94+
"virtualMachines": [
95+
{
96+
"name": "SE-CWAHL-WIN",
97+
"mountName": "MOUNT-2TIER-APP",
98+
"guestCred": "guestCred.xml",
99+
"testIp": "172.17.50.121",
100+
"testNetwork": "VLAN50_Servers_Mount",
101+
"testGateway": "172.17.50.1",
102+
"tasks": ["Ping","Netlogon"]
103+
},
104+
{
105+
"name": "SE-CWAHL-WIN",
106+
"mountName": "MOUNT-2TIER-DB",
107+
"guestCred": "guestCred.xml",
108+
"testIp": "172.17.50.122",
109+
"testNetwork": "VLAN50_Servers_Mount",
110+
"testGateway": "172.17.50.1",
111+
"tasks": ["Ping","Netlogon"]
112+
}
113+
]
114+
}
115+
```
116+
117+
#### Credentials
118+
The `Credentials` folder is not included in this repository. It can be placed anywhere in your environment and should host secure XML files created with `Export-Clixml` containing the credentials needed to communicate with the Rubrik cluster, vCenter Server, and any guest operating systems involved in the application testing.
119+
120+
Use the [`generateCreds.ps1`](https://github.com/rubrikinc/PowerShell-Backup-Validation/blob/master/helper/generateCreds.ps1) file to create a starter set of credentials or see how the generation process works. The script takes a single argument for the Path parameter, which will determine where the files are stored for the three types of credentials will be stored.
121+
122+
```
123+
param(
124+
$Path
125+
)
126+
127+
$CredType = @("rubrikCreds.xml","vmwareCreds.xml","guestCreds.xml")
128+
129+
foreach ($Type in $CredType) {
130+
$Credential = Get-Credential -Message $Type
131+
$Credential | Export-Clixml -Path ($Path + "\" + $Type)
132+
}
133+
```
134+
135+
#### Note
136+
Secure XML files can only be decrypted by the user account that created them, therefore they cannot be used by other users. Anyone that wants to run the build validation will have to generate their own set of credentials. In the following example I attempt to decrypt my credentials with a different user account, which fails as expected:
137+
138+
![alt text](/img/image3.png)
139+
140+
It is also important to note that these files can only be created on Windows systems. Both PowerShell and PowerShell Core support storing credentials on disk. This functionality is not available on other operating systems because Export-Clixml cannot be used to encrypt credentials as seen in the following screenshot running PowerShell Core on Ubuntu.
141+
142+
![alt text](/img/image4.png)
143+
144+
### Build Script
145+
The Build script is a script specifically written to be used in combination with the InvokeBuild module. There are a few concepts that are used by this module.
146+
147+
#### Build Tasks
148+
Tasks can be defined in the `.build.ps1` script, this is a specific alias to the `Add-BuildTask` function of the InvokeBuild Module. A task is like a PowerShell function, with some differences. Tasks can refer to multiple other tasks, but each of those tasks will only be invoked once.
149+
150+
An example of a simple task is the following which verifies the OS version by checking whether the OS is 32-bit or 64 bit:
151+
152+
```
153+
task OSVersion {
154+
if ((wmic os get osarchitecture) -match '64-bit') {
155+
'64'
156+
} else {
157+
'32'
158+
}
159+
}
160+
```
161+
162+
These tasks can be referenced in either multiple other tasks or can be called at the end of the build script.
163+
164+
##### Task Code Examples
165+
```
166+
task GetConfig {
167+
$script:Environment = Get-Content -Path $EnvironmentFile | ConvertFrom-Json
168+
$script:Config = Get-Content -Path $ConfigFile | ConvertFrom-Json
169+
# If a trailing backslash is omitted, this will make sure it's added to correct for future path + filename activities
170+
if ($IdentityPath.Substring($IdentityPath.Length - 1) -ne '\') {
171+
$script:IdentityPath += '\'
172+
}
173+
}
174+
```
175+
176+
This task is used to load the different configuration files that will be used by the other build tasks that follow this command.
177+
178+
```
179+
task ConnectVMware {
180+
$Credential = Import-Clixml -Path ($IdentityPath + $Environment.vmwareCred)
181+
$null = Connect-VIServer -Server $Environment.vmwareServer -Credential $Credential
182+
Write-Verbose -Message "VMware Status: Connected to $($global:DefaultVIServer.Name)" -Verbose
183+
}
184+
```
185+
186+
The `ConnectVMware` task is used to connect to the VMware cluster and will provide verbose information when successfully connected.
187+
188+
At the end of the script we will logically group together the different build tasks in 5 separate build tasks:
189+
190+
* 1_Init
191+
* 2_Connect
192+
* 3_LiveMount
193+
* 4_LiveMountNetwork
194+
* 5_Testing
195+
196+
```
197+
task 1_Init `
198+
GetConfig
199+
200+
task 2_Connect `
201+
ConnectRubrik,
202+
ConnectVMware
203+
204+
task 3_LiveMount `
205+
CreateLiveMount,
206+
ValidateLiveMount,
207+
ValidateLiveMountTools
208+
209+
task 4_LiveMountNetwork `
210+
MoveLiveMountNetwork,
211+
MoveLiveMountNetworkAddress
212+
213+
task 5_Testing `
214+
LiveMountTest
215+
```
216+
217+
The last line of the build script specific the tasks to be executed, the dot indicates the default build task:
218+
219+
```
220+
task . `
221+
1_Init,
222+
2_Connect,
223+
3_LiveMount,
224+
4_LiveMountNetwork,
225+
5_Testing,
226+
Cleanup
227+
```
228+
229+
This will run the tasks in the order they are specific, starting with the initialization of the configuration files and cleaning any remaining live mounts at the end of the validation.
230+
231+
#### Tests
232+
A `tests.ps1` file is also included in the package, this contains the tests that will be available during the build process. Every in the Config JSON files we specify which test will run against which VM.
233+
234+
An example of a test is the following ping test:
235+
236+
```
237+
task Ping {
238+
assert (Test-Connection -ComputerName $Config.testIp -Quiet) "Unable to ping the server."
239+
}
240+
```
241+
242+
The `tests.ps1` file can be updated with additional tests, and once these tests have been created they can be added to the Config JSON files for the relevant systems.
243+
244+
## Validate Backup
245+
Now that we have all components in place, we will create our own backup validation workflow.
246+
247+
### Prepare the Environment
248+
To get started we will download the Build Validation package and extract it to a folder named “Backup Validations”. The package is available in the [PowerShell-Backup-Validation](https://github.com/rubrikinc/Use-Case-PowerShell-Backup-Validation) repository. The zipped file is available for download [here](https://github.com/rubrikinc/PowerShell-Backup-Validation/archive/master.zip).
249+
250+
#### Configure Environment Files
251+
In the Environment files make sure that the correct IP addresses or FQDNs are listed for both the Rubrik Cluster as well as the vCenter cluster.
252+
253+
When specify the credentials, just the filename is required as we will specify the specific path when running the Invoke-Build function.
254+
255+
#### Configure Config Files
256+
In the Config files a number of configuration options are available:
257+
258+
* `Name` - the name of the VM
259+
* `mountName` - the name of the live mount
260+
* `guestCred` - the credentials file, only the filename is required, no path needs to be specified
261+
* `testIp` - IP Address configured for Live Mounted VM
262+
* `testNetwork` - virtual network used by the adapter of the Live Mount
263+
* `testGateway` - the gateway address of the network adapter
264+
* `tasks` - which tasks will run against this specific VM
265+
266+
#### Create the Credential files
267+
In order to save the credential files to disk, we will first create a `credentials` folder:
268+
269+
```
270+
mkdir ..\credentials
271+
```
272+
273+
![alt text](/img/image5.png)
274+
275+
After that we will use the `generateCreds.ps1` to generate the credential files required to connect to the different environments.
276+
277+
![alt text](/img/image6.png)
278+
279+
We can now verify that this command successfully created the files containing the encrypted credentials:
280+
281+
```
282+
Get-ChildItem ..\credentials\
283+
```
284+
285+
![alt text](/img/image7.png)
286+
287+
### Run `Invoke-Build`
288+
Once the Environment, Config, and Identity requirements are met, use the Invoke-Build function to execute a build. Here is a sample command using a PowerShell technique called splatting to store the parameters and arguments and execute `Invoke-Build`.
289+
290+
```
291+
$Splat = @{
292+
File = '.\.build.ps1'
293+
EnvironmentFile = '.\environment\testhost.json'
294+
ConfigFile = '.\config\TestConfiguration.json'
295+
IdentityPath = '.\credentials'
296+
}
297+
298+
Invoke-Build @Splat -Result Result
299+
```
300+
301+
![alt text](/img/image8.png)
302+
303+
When the build process is started we can see the Build Tasks are organized in the `1_Init/GetConfig` format, following the structure that was defined in `.build.ps1`.
304+
305+
![alt text](/img/image9.png)
306+
307+
Upon completion of all the build tests we can see that all our build tests have successfully been completed and no further action must be taken. Our backup validation process has been completed.
308+
309+
## Further Reading
310+
This section contains links to sources of documentation and information that provide further information about the individual components.
311+
312+
### Rubrik SDK for PowerShell
313+
[Rubrik SDK for PowerShell Documentation](http://rubrikinc.github.io/rubrik-sdk-for-powershell/)
314+
[VIDEO: Getting Started with the Rubrik SDK for PowerShell](https://www.youtube.com/watch?v=tY6nQLNYRSE)
315+
[Rubrik SDK for PowerShell](https://github.com/rubrikinc/rubrik-sdk-for-powershell)
316+
317+
### VMware PowerCLI
318+
[VMware PowerCLI User Guide](https://vdc-download.vmware.com/vmwb-repository/dcr-public/2156d7ad-8f0f-4001-9de5-0cb95340873b/84fc3e8c-4755-4376-9917-18eb49a6bcdf/vmware-powercli-111-user-guide.pdf)
319+
320+
### `InvokeBuild`
321+
[`Ivoke-Build` Project Wiki](https://github.com/nightroman/Invoke-Build/wiki)

‎docs/quickstart.md

-1
This file was deleted.

0 commit comments

Comments
 (0)