delete getting-started.md in favor of using wiki (#121)
This commit is contained in:
Wei Shi
GitHub
Родитель
54a5223aff
Коммит
c16b58a306
|
|
@ -1,36 +0,0 @@
|
|||
## Admin API Guidance
|
||||
AzureStack Hub Admin APIs are only for Operators. These APIs are exposed only via Admin AzureStack Hub Resource Manager. For example 'List all the subscriptions in an AzureStack Hub Environment' is an admin API.
|
||||
|
||||
### Developer flow
|
||||
Here is a recommended flow for developing an Admin API
|
||||
- Author Open API Spec and make a Pull Request
|
||||
- Notify azsdevexp alias for review
|
||||
- The PR is automatically reviewed by azure ARM team and SDK team for compliance
|
||||
- While the PR is in review, start developing the API. The PR could take more than a month to get it merged.
|
||||
- Start developing the Admin Powershell for the API from your fork. No need to wait until the Open API Spec PR is merged
|
||||
|
||||
Admin powershell is typically shipped within 2 weeks of the product update release.
|
||||
### Open API spec Authoring
|
||||
|
||||
Please look at the [docs](https://github.com/Azure/azure-rest-api-specs/tree/master/documentation) at the azure-rest-api-spec for guidance on authoring Open API Specs
|
||||
|
||||
### Admin powershell generation
|
||||
|
||||
Please look at the docs [here](https://github.com/Azure/azurestack-powershell/blob/master/docs/getting-started.md) to get started on the powershell generation
|
||||
|
||||
### FAQ
|
||||
|
||||
1. How to author an ARM API?
|
||||
|
||||
Please refer to the ARM guidance [here](https://github.com/Azure/azure-resource-manager-rpc)
|
||||
|
||||
2. When does an API need a new api-version?
|
||||
|
||||
Any breaking changes needs a new api version. Please refer to the [Breaking Change Policy](http://aka.ms/bcforapi) for detailed instructions on what constitutes as a breaking change
|
||||
|
||||
3. Do we need a new api version for adding a new API?
|
||||
|
||||
Adding an api to the existing api version is considered as a breaking change and we definitely need a newer api version. All customer environments are not getting the azure stack updates at the same time. Having a new API in the exsting api version will mislead the customer to try the new API in an older stamp which has not been updated. This is a breaking change. Azure Rest API specs team catches the breaking changes in the PR process itself and it will not get merged.
|
||||
|
||||
|
||||
For any other queries, please reach out to azsdevexp alias or use the Teams [channel](https://aka.ms/azsdevexp)
|
||||
|
|
@ -1,85 +0,0 @@
|
|||
Welcome to AzureStack Powershell repository!
|
||||
|
||||
The repo holds the modules for the AzureStack Hub operator persona. The Azurestack hub admin APIs are exposed as powershell via this repo
|
||||
|
||||
Most of the modules are generated with the autorest tool (https://github.com/Azure/autorest.powershell) and some modules are hand written.
|
||||
|
||||
## Contents
|
||||
### /src folder
|
||||
This is for source of all the admin api modules. This could also contain the helper cmdlets over azurestack/azure integration
|
||||
For many of the modules only the metadata configuration files would be present as the modules are generated as described in the following sections
|
||||
|
||||
### /tools folder
|
||||
This contains files that are essential for devops pipelines and security scans
|
||||
|
||||
### /docs folder
|
||||
This contains the migration guides and general information docs
|
||||
|
||||
## Dev Setup
|
||||
### Prerequisites
|
||||
1. Install NodeJs: https://nodejs.org/ (recommended v10, https://nodejs.org/download/release/v10.15.3/)
|
||||
a. Please do make sure that you have the recommended version. The latest seems to have issues in generation
|
||||
2. install new autorest beta packge:
|
||||
```
|
||||
npm install -g autorest
|
||||
```
|
||||
3. Install PS core:
|
||||
```
|
||||
npm install -g pwsh
|
||||
```
|
||||
4. Install .net core:
|
||||
```
|
||||
npm install -g dotnet-sdk-2.2
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
1. Go to module directory, e.g. src/Azs.Network.Admin
|
||||
2. Run:
|
||||
* autorest
|
||||
* pwsh
|
||||
* .\build-module.ps1
|
||||
3. All generated cmdlets will be inside 'exports' folder
|
||||
4. The module can be imported using the 'Azs.<ModuleName>.Admin.psd1' (e.g. Azs.Network.Admin.psd1) from the module directory
|
||||
|
||||
### Customizations:
|
||||
The docs for cusotmization can be found under https://github.com/Azure/autorest.powershell/tree/master/docs
|
||||
* Input specs files: declare it inside the readme.md file in the azure-rest-api-specs repo using input-file cmd
|
||||
e.g.
|
||||
``` yaml
|
||||
input-file:
|
||||
- "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/Network.json"
|
||||
- "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/LoadBalancers.json"
|
||||
- "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/PublicIpAddresses.json"
|
||||
- "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/Quotas.json"
|
||||
- "$(this-folder)/Microsoft.Network.Admin/preview/2015-06-15/VirtualNetworks.json"
|
||||
```
|
||||
* Include the above file in the azure-powershell module directory's readme.md file using require cmd
|
||||
|
||||
``` yaml
|
||||
require:
|
||||
- $(repo)/specification/azsadmin/resource-manager/network/readme.md
|
||||
```
|
||||
$(repo) and other common settings are defined in the [file](https://github.com/Azure/azurestack-powershell/blob/master/src/readme.azurestack.md)
|
||||
* Directives:
|
||||
Built-in Directives support renaming cmdlets/parameters/properties of models, adding alias, setting default value, etc. These are declared in readme.md and would take effect for the generated module. Refer to https://github.com/Azure/autorest/blob/master/docs/powershell/directives.md for the supported directives.
|
||||
Example: https://github.com/Azure/azure-powershell/blob/stackadmin/src/StackAdmin/Azs.Network.Admin/readme.md
|
||||
i. Removing InputObject parameter from the New-* cmdlet
|
||||
## variant removal (parameter InputObject) from all New cmdlets -- parameter sets CreateViaIdentity and CreateViaIdentityExpanded
|
||||
- where:
|
||||
verb: New
|
||||
variant: ^CreateViaIdentity(.*)
|
||||
remove: true
|
||||
|
||||
* Customization:
|
||||
For other customizations that directives do not support, use customization instead. Refer to https://github.com/Azure/autorest/blob/master/docs/powershell/customization.md for full instruction.
|
||||
A simple example is to change the param type from String to SecureString, to achieve this:
|
||||
1. Hide the cmdlet in md so that the original param with String type won't conflict with the SecureString param with same name;
|
||||
2. Generate the module and copy the .ps1 file from internal folder to custom folder;
|
||||
3. Edit the copied .ps1 file to do the customization. Change the param type to SecureString, and convert to plaintext inside cmdlet, replace the PSBoundParameters with the converted value;
|
||||
4. Call the internal cmdlet with the updated PSBoundParameters https://github.com/azure/azurestack-powershell/blob/master/src/Azs.Backup.Admin/custom/Set-AzsBackupConfiguration.ps1
|
||||
|
||||
### Tests
|
||||
Pester tests are required to make sure that cmdlets are validated against a live azurestack environment. Also to make sure that the future changes are not breaking the cmdlets. We follow the record and playback framework used by the azure powershell team.
|
||||
The docs for authoring the tests can be found at the following wiki
|
||||
https://github.com/Azure/azure-powershell/wiki/How-to-On-Board-New-RP-with-Azure-PowerShell-Generator#test
|
||||
Загрузка…
Ссылка в новой задаче