Repository navigation
Improve Task Documentation #68
Description
There is a significant gap in parameter input documentation.
Currently the only place to find this information I am aware of is through the UI and hover over the info indicators:
This is a huge learning curve/hurtle for customer adoption.
Here is an example from other MS tasks: https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/reference/azure-resource-manager-template-deployment-v3?view=azure-pipelines
# ARM template deployment v3
# Deploy an Azure Resource Manager (ARM) template to all the deployment scopes.
- task: AzureResourceManagerTemplateDeployment@3
inputs:
# Azure Details
deploymentScope: 'Resource Group' # 'Management Group' | 'Subscription' | 'Resource Group'. Required. Deployment scope. Default: Resource Group.
azureResourceManagerConnection: # string. Alias: ConnectedServiceName. Required. Azure Resource Manager connection.
#subscriptionId: # string. Alias: subscriptionName. Required when deploymentScope != Management Group. Subscription.
#action: 'Create Or Update Resource Group' # 'Create Or Update Resource Group' | 'DeleteRG'. Required when deploymentScope = Resource Group. Action. Default: Create Or Update Resource Group.
#resourceGroupName: # string. Required when deploymentScope = Resource Group. Resource group.
#location: # string. Required when action = Create Or Update Resource Group || deploymentScope != Resource Group. Location.
# Template
#templateLocation: 'Linked artifact' # 'Linked artifact' | 'URL of the file'. Required when action = Create Or Update Resource Group || deploymentScope != Resource Group. Template location. Default: Linked artifact.
#csmFileLink: # string. Required when templateLocation = URL of the file && action = Create Or Update Resource Group || deploymentScope != Resource Group. Template link.
#csmParametersFileLink: # string. Optional. Use when templateLocation = URL of the file && action = Create Or Update Resource Group || deploymentScope != Resource Group. Template parameters link.
#csmFile: # string. Required when templateLocation = Linked artifact && action = Create Or Update Resource Group || deploymentScope != Resource Group. Template.
#csmParametersFile: # string. Optional. Use when templateLocation = Linked artifact && action = Create Or Update Resource Group || deploymentScope != Resource Group. Template parameters.
#overrideParameters: # string. Optional. Use when action = Create Or Update Resource Group || deploymentScope != Resource Group. Override template parameters.
#deploymentMode: 'Incremental' # 'Incremental' | 'Complete' | 'Validation'. Required when action = Create Or Update Resource Group || deploymentScope != Resource Group. Deployment mode. Default: Incremental.
# Advanced
#deploymentName: # string. Optional. Use when action = Create Or Update Resource Group || deploymentScope != Resource Group. Deployment name.
#deploymentOutputs: # string. Optional. Use when action = Create Or Update Resource Group || deploymentScope != Resource Group. Deployment outputs.
#addSpnToEnvironment: false # boolean. Optional. Use when action = Create Or Update Resource Group || deploymentScope != Resource Group. Access service principal details in override parameters. Default: false.
Activity
JiandongJiang commentedon Jul 13, 2023
Thanks for the feedback. I will bring it up for team's attention for prioritization.
JFolberth commentedon Aug 10, 2023
Jiandong Jiang (@JiandongJiang) has there been anymore thought on this as without this documentation the product does not feel complete or ready for mass consumption.
JiandongJiang commentedon Aug 10, 2023
Yes, our team ack'd it and was prioritizing it for documentation improvements. Thanks.
fabio-s-franco commentedon Sep 27, 2023
Jiandong Jiang (@JiandongJiang) There is literally nothing of documentation on how to use this besides the bear mention on how to add the extension without any configuration:
https://learn.microsoft.com/en-us/azure/defender-for-cloud/azure-devops-extension#configure-your-pipelines-using-yaml
Which makes this practically impossible to adopt.
JiandongJiang commentedon Sep 28, 2023
Fábio Franco (@fabio-s-franco) , thanks for the feedback. Our team ack'd it and is working on the documentation improvements. Thanks.
JFolberth commentedon Sep 28, 2023
Jiandong Jiang (@JiandongJiang) unfortunately it's responses like this in addition to lack of engagement, see issues and PRs, that leads me to steer customers away from Defender for DevOps and prioritize other solutions that fill this technology gap.
JiandongJiang commentedon Oct 3, 2023
The requested updates to the mentioned documentation will be deployed soon per schedule. Our PM Sukhandeep Singh (@sukhans) will be updating this thread for closure once the updates go live. Thanks.
fabio-s-franco commentedon Oct 28, 2023
JFolberth I don't have issues with the response itself, I am sure Jiandong Jiang (@JiandongJiang) is doing what's within his reach. But I do agree. The lack of engagement and very poor management leads to this. Half baked, solutions that don't get enough attention.
I already moved on, there is no way I am gonna spend energy here. If it takes months to add simple documentation, what should I expect if I run into issues. Thank you, but no thank you.
charlesoxyer commentedon Oct 29, 2023
Hi JFolberth, Fábio Franco (@fabio-s-franco), my name is Charles Oxyer, and I first want to apologize for the slow and unacceptable response time in this matter. I am taking over PM responsibilities for the MSDO task, and first want to let you know the parameter inputs are documented here: https://github.com/microsoft/security-devops-azdevops/wiki#msdo-task-configuration and will be included as part of a full documentation overhaul we are working on for the DevOps security features in Defender for Cloud documentation.
If you are willing to give DevOps security in Defender for Cloud a second chance, you can reach out directly to me with feedback/issues you encounter and I hope the capabilities we continue to ship over the coming months change your mind about our product. [my_github_username]@microsoft.com.