API-avaimen käyttöoikeudet

API-avain todentaa ohjelman — CI:n, skriptin, Terraformin — Frostmolnin API:a vastaan. Jokaisella avaimella on käyttöoikeudet (scopes): luettelo siitä, mitä se saa tehdä. Frostmolnin avaimet noudattavat vähimmän oikeuden periaatetta, joten avain ei tee mitään ennen kuin määrität, mitä se saa tehdä.

Luettelon tarjoaa alusta

Tällä sivulla ei ole kiinteää luetteloa kopioitavaksi. Luettelo sijaitsee alustalla, joten se vastaa aina sitä, mitä avaimen luonti hyväksyy. Lue se siltä pinnalta, jolla työskentelet:

Missä	Miten
Portaali	Asetukset → API-avaimet → Luo API-avain. Käyttöoikeusvalitsin listaa jokaisen käyttöoikeuden ja kuvauksen siitä, mitä se antaa.
CLI	fm account api-key scopes (lisää -o json skriptausta varten).
Terraform	Tietolähde frostmoln_api_key_scopes — aja terraform console ja sitten data.frostmoln_api_key_scopes.all.scopes.

Miltä käyttöoikeus näyttää

Käyttöoikeus kirjoitetaan muodossa <palvelu>:<toiminto>:

compute:read     lukea compute-resursseja
compute:write    luoda, muuttaa ja poistaa niitä
storage:read     lukea levyjä ja bucketteja
billing:read     lukea laskuja ja käyttöä

read ja write ovat ne kaksi toimintoa, jotka API tänään valvoo. write kattaa jokaisen muutoksen — luonnin, päivityksen, poiston sekä toiminnot kuten käynnistys/pysäytys/uudelleenkäynnistys. Erillistä "luo mutta älä poista" -käyttöoikeutta ei ole: kun tarvitset sen eron, käytä käyttöoikeuskäytäntöä.

Anna read ja write, älä hienompia muotoja

Luettelossa on myös kolmiosaisia merkintöjä kuten compute:instances:read, ja avaimen luonti hyväksyy ne. Niitä ei valvota avaimen käyttöoikeuksina — ne kuuluvat käyttöoikeuskäytäntö-moottorille. Avain, jolla on vain compute:instances:read, luodaan virheittä ja evätään sitten jokaisella compute-kutsulla 403-virheellä, joka ei kerro syytä.

Sama koskee luettelon muita verbejä (action, create, update, delete, list): ne voidaan antaa, mutta palvelut tarkistavat :read ja :write. Anna ne.

Jokerimerkit

Käyttöoikeus	API-avain	Työkuormaidentiteetti
* (kaikki)	Hylätään — WILDCARD_SCOPE_NOT_ALLOWED	Hylätään — WILDCARD_SCOPE_FORBIDDEN
compute:* (yksi palvelu)	Sallitaan	Hylätään — WILDCARD_SCOPE_FORBIDDEN
compute:read	Sallitaan	Sallitaan

Workload Identity -sidos on tarkoituksella tiukempi kuin API-avain: federoidun podin tunnistetiedon on nimettävä täsmälleen se, mitä se tarvitsee.

Huomaa, että compute:* antaa todella kaiken, mitä kyseinen palvelu tarjoaa nyt ja tulevaisuudessa. Kaksi nimettyä käyttöoikeutta on lähes aina parempi valinta.

Sääntöjä, jotka on hyvä tietää

• Vähintään yksi käyttöoikeus vaaditaan. Tyhjä lista hylätään virheellä SCOPES_REQUIRED ja tuntematon käyttöoikeus virheellä INVALID_SCOPES (avainta luotaessa; INVALID_SCOPE, kun avainta tai työkuormasidosta päivitetään).
• Avain ei voi koskaan ylittää sinua — sillä hetkellä, kun luot sen. Käyttöoikeudet rajataan avaimen luovan identiteetin oikeuksiin; suuremman pyytäminen epäonnistuu virheellä SCOPE_EXCEEDS_PERMISSIONS. Tämä tarkistetaan avainta luotaessa tai sen käyttöoikeuksia muutettaessa. Jos omat oikeutesi vähenevät myöhemmin, jo myönnetyt avaimet säilyttävät käyttöoikeutensa — peru ne ja myönnä uudelleen.
• Organisaation hallintaa eivät ohjaa käyttöoikeudet. Organisaation poistamisen, jäsenten muuttamisen ja omistajuuden siirron valtuuttaa organisaatioroolisi, ei avaimen käyttöoikeudet — omistajan luoma avain voi tehdä ne riippumatta siitä, mihin se on rajattu. Älä pidä kapeaa käyttöoikeuslistaa suojana organisaatiotason muutoksia vastaan: luo automaatioavaimet tilillä, joka ei ole organisaation omistaja.

Käyttöoikeuksien valinta

Lähde liikkeelle tehtävästä, jonka avain hoitaa, älä palvelusta, jota se kutsuu.

Avain tekee tämän	Anna
Valvonta / inventointi	compute:read, storage:read, network:read — tarkasteltavien lukuoikeudet
Instansseja käyttöönottava CI	compute:read, compute:write
Palvelun ajastettu uudelleenkäynnistys	compute:read, compute:write (toiminto on muutos)
Koko pinoa hallitseva Terraform	read ja write jokaiselle pinon palvelulle — suunnitelma lukee ennen kuin se muuttaa mitään
Laskujen luku kirjanpitoa varten	billing:read

Kaksi tapaa pitää avaimet turvallisina: anna avaimelle yksi tehtävä sen sijaan, että käyttäisit laajaa avainta uudelleen, ja aseta vanhenemisaika, jotta unohtunut avain lakkaa toimimasta itsestään.

Esimerkkejä

CLI

# Katso mitä voit antaa, luo sitten avain
fm account api-key scopes
fm account api-key create --name "ci-deploy" \
  --scopes compute:read,compute:write \
  --expires 2027-01-01

Terraform

data "frostmoln_api_key_scopes" "all" {}

resource "frostmoln_api_key" "ci" {
  name   = "ci-deploy"
  scopes = ["compute:read", "compute:write"]
}

Itse avain näytetään kerran, luonnin yhteydessä. Tallenna se heti salaisuuksien hallintaan — sitä ei voi hakea myöhemmin, vain korvata.

Kun käyttöoikeudet eivät riitä

Käyttöoikeudet kertovat, minkä tyyppisiä kutsuja avain saa tehdä, eivät koskaan mille resurssille tai mistä käsin. Kun tarvitset "saa luoda instansseja mutta ei koskaan poistaa niitä", "vain yhdellä alueella", "vain toimistoverkosta" tai nimenomaisen kiellon, käytä käyttöoikeuskäytäntöä. Siellä hienojakoiset service:resource:action-operaatiot pätevät, ja käytäntö liitetään samoihin API-avaimiin.