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öä

Lähes jokaisessa palvelussa read ja write ovat ne kaksi toimintoa, joita API valvoo (istuntokäyttöoikeudet ovat oma luokkansa — katso alta). 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 useimpia luettelon muita verbejä (action, create, update, delete, list): ne voidaan antaa, mutta palvelut tarkistavat :read ja :write. Anna ne.

Istuntokäyttöoikeudet ovat oma luokkansa. sessions:forward, sessions:pty ja sessions:write ovat todellisia käyttöoikeusmerkkijonoja, koska istunto on oma etuoikeutensa eikä toiminto resurssiin, johon se yltää. Mikään muu ei aja niiden asiaa: compute:action ei ole se käyttöoikeus, joka avaa päätteen instanssiin, eikä kubernetes:* ole se, joka avaa klusterin API-välityspalvelimen. Anna ne jokaiselle avaimelle, joka ajaa fm forward, fm database <type> console, fm shell tai fm kubernetes cluster proxy.

Ne tarkistetaan avainta luotaessa: et voi antaa avaimelle käyttöoikeutta, jota omalla roolillasi ei ole, joten sessions:pty vaatii Owner-, Administrator-, Developer- tai Member-roolin. Niitä ei vielä tarkisteta istuntoa avattaessa — tänään avain, jolta ne puuttuvat, voi silti avata istunnon. Myönnä ne jo nyt, niin avaimesi ovat valmiiksi oikein, kun tuo tarkistus tulee voimaan.

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 hallinta vaatii kirjautuneen henkilön, ei avainta. Organisaation poistaminen, jäsenen roolin muuttaminen, jäsenen poistaminen, organisaatiosta poistuminen ja omistajuuden siirto evätään jokaiselta API-avaimelta riippumatta siitä, mihin avain on rajattu — myös *. Avain, jolla on organizations:write, saa virheen USER_SESSION_REQUIRED; avain ilman sitä saa ensin virheen insufficient_scope. Tee ne portaalissa kirjautuneena. Organisaatiosta poistuminen ei ole vielä portaalissa, joten pyydä ylläpitäjää tai omistajaa poistamaan sinut (ylläpitäjän on pyydettävä omistajaa); omistajan on ensin siirrettävä omistajuus ja pyydettävä sitten uutta omistajaa. Muut organisaatiotason muutokset, kuten jäsenten kutsuminen, vaativat avaimelle käyttöoikeuden organizations:write sekä organisaatioroolin, joka sallii ne.
• Avain ulottuu yhteen organisaatioon: siihen, joka omistaa sen tenantin. Vaikka kuuluisit useaan organisaatioon, yhden organisaation tenantissa luotu avain ei voi lukea tai muuttaa toista. Kun listaat organisaatiot avaimella, näet vain sen yhden, ja mikä tahansa muu organisaatio hylätään virheellä ORGANIZATION_ACCESS_DENIED. Luo avain jokaisen automatisoimasi organisaation tenanttiin.
• Useimmat fm tenant -komennot vaativat käyttöoikeuden organizations:read. Tenanttien listaaminen, vaihtaminen komennolla fm tenant use ja oletustunnisteiden lukeminen komennolla fm tenant default-tags get vaativat käyttöoikeuden organizations:read. Tenantin luominen, uudelleennimeäminen tai sen oletustunnisteiden muuttaminen vaatii käyttöoikeuden organizations:write, ja luominen ilman valitsinta --organization vaatii lisäksi käyttöoikeuden organizations:read. fm tenant current ei vaadi kumpaakaan. fm tai portaali ei voi muuttaa olemassa olevan avaimen käyttöoikeuksia (Terraform-resurssi frostmoln_api_key voi päivittää luomaansa avainta): luo uusi avain, vaihda siihen komennolla fm auth api-key set ja peru sitten vanha komennolla fm account api-key revoke.
• Kiintiöpyynnöt vaativat käyttöoikeuden quotas:write. Pyynnön lähettäminen tai peruminen komennolla fm tenant quota request vaatii käyttöoikeuden quotas:write, ja pyyntöjen listaaminen käyttöoikeuden quotas:read. compute:write ja compute:* eivät riitä: hyväksytty tenantin korotus nostaa kustannuskattoa, ja se on eri oikeus kuin resurssien luominen. Olemassa olevat avaimet eivät saaneet uutta käyttöoikeutta, joten kiintiöpyyntöjä lähettävä automaatio tarvitsee uuden avaimen, jolla on quotas:write. Workload identityllä voi olla quotas:read, mutta ei koskaan quotas:write. Itse kiintiöiden lukeminen (fm tenant quota, tietolähde frostmoln_tenant_quotas) ei vaadi kumpaakaan.

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
Kiintiömuutosten pyytäminen	quotas:read, quotas:write

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.